Zenscroll

https://github.com/zengabor/zenscroll
Admin
Zenscroll is a lightweight vanilla JavaScript library that enables smooth animated vertical...
Tokens:4,833
Snippets:63
Trust Score:7.2
License:Unlicense
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Zenscroll via npm

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Use the npm package manager to install Zenscroll.

```bash
npm install zenscroll
```

--------------------------------

### Get current vertical scroll position

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Retrieves the current vertical scroll position for the body or a specific scroller instance.

```js
var bodyY = zenscroll.getY()

var myDivY = myDivScroller.getY()
```

--------------------------------

### Get top position of an element

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Calculates the top position of an element relative to the body or a specific scroller, excluding edge offsets.

```js
var myElemY = zenscroll.getTopOf(myElem)

var relativeTopOfElem = myDivScroller.getTopOf(anElemInMyDiv)
```

--------------------------------

### zenscroll.setup(duration, edgeOffset)

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Configures the default scroll duration and edge offset for the scroller. Passing null for a parameter leaves the existing value unchanged.

```APIDOC
## zenscroll.setup(duration, edgeOffset)

### Description
Configures the default scroll duration and edge offset. If no parameters are provided, it returns the current settings object.

### Parameters
- **duration** (number) - Optional - Default duration in milliseconds.
- **edgeOffset** (number) - Optional - Spacing in pixels between the element and the screen edge.

### Returns
- **Object** - Returns an object containing {defaultDuration, edgeOffset}.
```

--------------------------------

### Enable native smooth-scrolling with CSS

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Set the scroll-behavior property to smooth to leverage native browser smooth-scrolling where available.

```css
body, .smooth-container { scroll-behavior: smooth }
```

--------------------------------

### Retrieve current settings

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Obtains the current configuration object containing defaultDuration and edgeOffset.

```js
var currentSettings = zenscroll.setup()
var dd = currentSettings.defaultDuration
var eo = currentSettings.edgeOffset
```

--------------------------------

### zenscroll.center(element, duration, offset, onDone)

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Scrolls an element to the center of the screen.

```APIDOC
## zenscroll.center(element, duration, offset, onDone)

### Description
Scrolls the element to the center of the screen. An optional offset can be provided to adjust the vertical position.

### Parameters
- **element** (HTMLElement) - Required - The element to center.
- **duration** (number) - Optional - Duration of the scroll in milliseconds.
- **offset** (number) - Optional - Pixels to shift the top of the element upwards from the center.
- **onDone** (function) - Optional - Callback function executed when scrolling is finished.
```

--------------------------------

### zenscroll.intoView(element, duration, onDone)

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Scrolls an element into the visible viewport.

```APIDOC
## zenscroll.intoView(element, duration, onDone)

### Description
Scrolls an element into view. If the element is already fully visible, no scroll is performed.

### Parameters
- **element** (HTMLElement) - Required - The element to scroll into view.
- **duration** (number) - Optional - Duration of the scroll in milliseconds.
- **onDone** (function) - Optional - Callback function executed when scrolling is finished.
```

--------------------------------

### Configure custom scroller settings

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Updates the duration and offset for a specific custom scroller instance.

```js
myScroller.setup(500, 10)
```

--------------------------------

### zenscroll.createScroller(element, defaultDuration, edgeOffset)

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Instantiates a new scroller for a specific scrollable container.

```APIDOC
## zenscroll.createScroller(element, defaultDuration, edgeOffset)

### Description
Creates a scroller instance for a specific scrollable DIV or element. The container must have a CSS position of relative, absolute, or fixed.

### Parameters
- **element** (HTMLElement) - Required - The scrollable container element.
- **defaultDuration** (number) - Optional - Default duration for scroll operations.
- **edgeOffset** (number) - Optional - Default edge offset for the scroller.
```

--------------------------------

### zenscroll.getY()

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Retrieves the current vertical scroll position.

```APIDOC
## zenscroll.getY()

### Description
Returns the current vertical scroll position in pixels.

### Returns
- **number** - The vertical scroll position.
```

--------------------------------

### zenscroll.toY(y, duration, onDone)

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Scrolls the document to a specific vertical position.

```APIDOC
## zenscroll.toY(y, duration, onDone)

### Description
Scrolls the document to a specific vertical position in pixels.

### Parameters
- **y** (number) - Required - The vertical position in pixels.
- **duration** (number) - Optional - Duration of the scroll in milliseconds.
- **onDone** (function) - Optional - Callback function executed when scrolling is finished.
```

--------------------------------

### Execute callback after scrolling

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Provides a callback function to be executed when the scroll operation completes.

```javascript
// Last line of example 1:
zenscroll.intoView(container, 100, function () { myScroller.center(target) })

// Example 2:
zenscroll.intoView(container, 100, function () { myScroller.toY(35) })

// Example 3:
zenscroll.intoView(container, 100, function () { myScroller.intoView(target) })
```

--------------------------------

### Configure default duration and edge offset

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Sets the global default duration and edge offset for all scroll operations.

```js
var defaultDuration = 777 // ms
var edgeOffset = 42 // px
zenscroll.setup(defaultDuration, edgeOffset)
```

--------------------------------

### Scrollable container toY

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Perform a vertical scroll within a custom scroller instance.

```javascript
myScroller.toY(500)
```

--------------------------------

### Scroll an element into view

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Scrolls the page so that the specified element is visible. If the element is already fully visible, no scroll is performed.

```javascript
zenscroll.intoView(image1)
```

--------------------------------

### Scrollable container intoView

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Scroll an element into view within a custom scroller instance.

```javascript
myScroller.intoView(target)
```

--------------------------------

### zenscroll.moving()

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Checks if a scroll operation is currently in progress.

```APIDOC
## zenscroll.moving()

### Description
Returns a boolean indicating whether a scroll is currently being performed.

### Returns
- **boolean** - True if scrolling, false otherwise.
```

--------------------------------

### Disable automatic smoothing on local links

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Set window.noZensmooth to true before loading the Zenscroll script to disable automatic event handlers for local links.

```html
    ...
    <script>window.noZensmooth = true</script>
    <script src="zenscroll-min.js"></script>
</body>
```

--------------------------------

### Set scroll duration toY

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Sets the duration in milliseconds for a vertical scroll to a specific Y position.

```javascript
zenscroll.toY(50, 100) // 100ms == 0.1 second
```

--------------------------------

### Disable scroll smoothing

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Setting the duration to zero results in an immediate jump without smoothing.

```javascript
zenscroll.to(about, 0) // 0 milliseconds == no smoothing
```

--------------------------------

### Scroll inside a scrollable DIV

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Instantiate a new scroller for a specific container element. The container must have a position property set to relative, absolute, or fixed.

```html
<div id="container" style="position: relative">
  <div id="item1">ITEM 1</div>
  <div id="item2">ITEM 2</div>
  <div id="item3">ITEM 3</div>
  <div id="item4">ITEM 4</div>
  <div id="item5">ITEM 5</div>
  <div id="item6">ITEM 6</div>
  <div id="item7">ITEM 7</div>
</div>

<script>
  var defaultDuration = 500
  var edgeOffset = 30
  var myDiv = document.getElementById("container")
  var myScroller = zenscroll.createScroller(myDiv, defaultDuration, edgeOffset)
  var target = document.getElementById("item4")
  myScroller.center(target)
</script>
```

--------------------------------

### Include Zenscroll via script tag

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Include the Zenscroll script at the bottom of your page before the closing body tag.

```html
    ...
    <script src="zenscroll-min.js"></script>
</body>
```

--------------------------------

### Update only default duration

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Updates the default duration while leaving other settings unchanged by omitting the second parameter.

```js
zenscroll.setup(777) // only updates defaultDuration to 777
```

--------------------------------

### zenscroll.getTopOf(element)

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Calculates the top position of a specific element relative to the scroller.

```APIDOC
## zenscroll.getTopOf(element)

### Description
Returns the top position of an element within the body or a scroller, excluding edge offsets.

### Parameters
- **element** (HTMLElement) - Required - The target element to measure.

### Returns
- **number** - The top position in pixels.
```

--------------------------------

### Scroll element to center with offset

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Scrolls the element to the center with a custom duration and vertical offset.

```javascript
var duration = 500 // milliseconds
var offset = 200 // pixels
zenscroll.center(image2, duration, offset)
```

--------------------------------

### zenscroll.stop()

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Immediately stops any ongoing scroll operation.

```APIDOC
## zenscroll.stop()

### Description
Terminates the current scrolling animation.
```

--------------------------------

### Scroll element to center of screen

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Scrolls the specified element to the center of the viewport.

```javascript
zenscroll.center(image2)
```

--------------------------------

### Set scroll duration to element

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Sets the duration in milliseconds for scrolling to a specific element.

```javascript
zenscroll.to(about, 500) // 500ms == half a second
```

--------------------------------

### Postpone scrolling after element resize

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Use setTimeout to delay the scroll operation, useful when an element's size changes due to a CSS transition.

```javascript
image.classList.remove("is-small")
setTimeout(function () { 
    zenscroll.intoView(image2) 
}, 500)
```

--------------------------------

### Update only edge offset

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Updates the edge offset while leaving the default duration unchanged by passing null as the first parameter.

```js
zenscroll.setup(null, 42) // only updates edgeOffset to 42
```

--------------------------------

### Set scroll duration for center

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Sets the duration in milliseconds for centering an element.

```javascript
zenscroll.center(image2, 2000) // 2 seconds
```

--------------------------------

### Scroll to the top of an element

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Use the zenscroll.to method to programmatically scroll to a specific DOM element. Zenscroll defaults to leaving a 9px edge offset, which can be adjusted globally or per-scroller.

```javascript
var about = document.getElementById("about")
zenscroll.to(about)
```

--------------------------------

### Exclude a link from automatic smooth-scrolling

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Add the noZensmooth class to an anchor element to prevent Zenscroll from animating the scroll for that specific link.

```html
<a href="#about" class="noZensmooth">
```

--------------------------------

### Stop current scrolling

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Immediately halts any ongoing scroll animation.

```js
zenscroll.stop()
```

--------------------------------

### Scroll to a specific vertical position

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Scrolls the document to a specific vertical coordinate in pixels.

```javascript
zenscroll.toY(50)
```

--------------------------------

### Check if scrolling is active

Source: https://github.com/zengabor/zenscroll/blob/dist/README.md

Returns a boolean indicating whether a scroll operation is currently in progress.

```js
var isScrolling = zenscroll.moving()
```
Tokens:
Raw