source: node_modules/zenscroll/README.md

main
Last change on this file was d24f17c, checked in by Aleksandar Panovski <apano77@…>, 15 months ago

Initial commit

  • Property mode set to 100644
File size: 16.1 KB
Line 
1<p align="center">
2 <a href="https://zengabor.github.io/zenscroll/">
3 <img src="https://zengabor.github.io/zenscroll/zenscroll.png" alt="Zenscroll">
4 </a>
5</p>
6
7
8#### [**Demo**](https://zengabor.github.io/zenscroll/) &nbsp; &nbsp; &nbsp; &nbsp; [**Download**](https://github.com/zengabor/zenscroll/archive/latest.zip) &nbsp; &nbsp; &nbsp; &nbsp; [**About**](#about) &nbsp; &nbsp; &nbsp; &nbsp; [**Install**](#install) &nbsp; &nbsp; &nbsp; &nbsp; [**How to use**](#how-to-use) &nbsp; &nbsp; &nbsp; &nbsp; [**License**](#license)
9
10
11# One JavaScript to Smooth-Scroll&nbsp;Them&nbsp;All
12
13Smooth animated scrolling. Move&nbsp;elements&nbsp;into&nbsp;view, or&nbsp;scroll&nbsp;to any vertical&nbsp;position.
14
151.4&nbsp;kilobyte of vanilla&nbsp;JavaScript. No&nbsp;dependencies.
16
17
18
19## About
20
21Zenscroll is a vanilla JavaScript library that enables animated vertical scrolling to an element or position within your document or within a scrollable element (DIV, etc.). It can also automatically smooth all scrolling within the same page.
22
23Features:
24
25- Smooth animated vertical scrolling.
26- Automatic smooth-scrolling on links within the same page, including back and forward navigation (Chrome, Firefox, Opera, Safari Technology Preview).
27- Scroll to the top of a specific element.
28- Scrolling an element into view, making sure both top & bottom are visible, if possible.
29- Scroll to an element and center it on the screen.
30- Specify the spacing between the element and the edge of the screen (e.g., for fixed navigation bars and footers).
31- Customize the duration of the individual scroll operations.
32- Callback when the scrolling is done.
33- Can use new browser’s built-in smooth-behavior if it’s enabled.
34- Just 1.4 kilobyte minimized & gzipped.
35- No dependencies.
36
37Full support tested and works under:
38
39- Android Browser 2.2+
40- Chrome for Android
41- Chrome 14+ (probably earlier too)
42- Edge
43- Firefox 9+
44- Internet Explorer 9+
45- iOS Safari 4+
46- Opera 10.6+ (probably earlier too)
47- Safari 4+
48- Windows Phone 8.1
49- Yandex 14.12
50
51Limited support (programmatic animated scroll in document) tested and works under:
52
53- Firefox 3+
54- Internet Explorer 6+
55- iOS Safari 3+
56
57
58## Getting Started
59
60### Installing Zenscroll
61
62[Download Zenscroll](https://github.com/zengabor/zenscroll/archive/latest.zip) and include it into your page. A good place is at the very bottom, just before the closing `</body>` tag. For&nbsp;example:
63
64````html
65 ...
66 <script src="zenscroll-min.js"></script>
67</body>
68````
69
70Zenscroll will also work if you reference it in the `<head>` but it is not recommended for performance reasons. Important: You can only call Zenscroll when `document.body` is already available, so don’t try to call Zenscroll functions from the `<head>`.
71
72You can also [get Zenscroll via npm](https://www.npmjs.com/package/zenscroll):
73
74````
75npm install zenscroll
76````
77
78
79### Enabling native smooth-scrolling in the browser
80
81If you want to leverage the native smooth-scrolling by the browser (currently available in Firefox 36+ and Chrome 49+) then set the [`scroll-behavior` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior) to `smooth` on the body and on the elements you want to scroll. E.g.,
82
83````css
84body, .smooth-container { scroll-behavior: smooth }
85````
86
87If this is set, Zenscroll will use built-in smooth-scrolling in capable browsers while still animating the scroll in older browsers. However, note that if you use the native smooth-scrolling then you loose the finer control options that Zenscroll offers: the speed settings of the animation, and the edge offset for links within the page. Only set this CSS property on the `body` or on the elements if you don’t need this level of control.
88
89
90### Disabling automatic smoothing on local links
91
92If you want to use Zenscroll programmatically but you don’t need the automatic smoothing on local links then set `window.noZensmooth` to a non-falsy value. In this case the event handler for automatic smoothing is not installed but you can still use everything, like `zenscroll.intoView()`, etc.
93
94It’s important to set this value before Zenscroll is executed, otherwise the handlers will be installed. So make sure the setting comes before the loading of the script. For&nbsp;example:
95
96````html
97 ...
98 <script>window.noZensmooth = true</script>
99 <script src="zenscroll-min.js"></script>
100</body>
101````
102
103(I consider the disabling of the automatic smooth-scrolling a rather rare scenario that’s why I install the event handlers by default.)
104
105
106## How to use
107
108
109### 1. Automatic smooth-scroll to links within the page
110
111If Zenscroll is included in your page it will automatically animate the vertical scrolling to anchors on the same page. No further setting is required. (Note that it can be disabled, see [1.5](#1.5.disabletheautomaticsmooth-scrolling).)
112
113Automatic smooth-scrolling works also with content you dynamically load via AJAX, as Zenscroll uses a generic click handler. Since the automatic smooth-scrolling is implemented a progressive enhancement, internal links work in older browsers as well.
114
115#### 1.1. Automatic edge offset adjustment on load
116
117Zenscroll automatically adds the configured edge offset when the page is loaded with a hash suffix. For example, if you navigate to `"http://yoursite.com/#about"` then the scroll position will be not cut sharply at the top edge of the element with `id="above"`. Instead, Zenscroll automatically adds the configured edge offset (which is 9 pixels by default, unless you [changed it](#9.changesettings)).
118
119No automatic adjustment happens in the following cases:
120
121- If automatic smooth-scroll is disabled via `noZensmooth` or the native smooth-scrolling (see [1.5](#1.5.disabletheautomaticsmooth-scrolling))
122- If edge offset was set to zero (e.g., `zenscroll.setup(null, 0)`).
123
124#### 1.2. Limited support for smooth back & forward navigation
125
126The scroll is also animated when the browser’s back and forward buttons or the relevant key combinations are used (or even if the navigation is invoked from JavaScript). Note that although Zenscroll remembers the vertical scroll position, it cannot calculate changes caused by browser window resizing or collapsing/expanding elements, etc.
127
128This functionality requires browser support for `history.scrollRestoration` which is available for example in Chrome 46+, Firefox 46+, and Safari Technology Preview.
129
130#### 1.3. Limited support for the `hashchange` event and the CSS pseudo `:target`
131
132The automatic smooth-scroll on local links can also trigger the standard `hashchange` event and the CSS pseudo-class `:target` but only if you set the edge offset to 0. I had to introduce this limitation because otherwise the scrolling isn’t smooth.
133
134So if you need `hashchange` or `:target` then make sure you execute `zenscroll.setup(null, 0)`.
135
136#### 1.4. No support for automatic scroll to elements inside scrollable elements
137
138Zenscroll wants to be a lightweight solution for animated vertical scrolling, that works in most browsers. The automatic link-scrolling is even more focused on anchors that are directly inside the page body. Unfortunately it won’t scroll accurately to elements that are inside other scrollable elements (e.g., `overflow: auto; max-height: 100px`). Don’t expect Zenscroll to re-implement the full functionality of the browser, with the recursive logic of traversing the nested scrollable elements.
139
140So, how to deal with a situation like this? Try one of the following methods:
141
142- Exclude the problematic links from the automatic smooth-scrolling (see [1.6.](#1.6.excludealinkfromtheautomaticsmooth-scrolling)).
143- Or implement the special logic programatically (see [7\. Scroll inside a scrollable DIV](#7.scrollinsideascrollablediv)).
144- Or don’t use Zenscroll at all. Instead, rely on the browser’s built-in scrolling, and enable the native smooth-scrolling (via `body { scroll-behavior: smooth }`) which works in new browsers.
145
146#### 1.5. Disable the automatic smooth-scrolling
147
148The automatic smooth-scrolling is completely disabled in the following cases:
149
1501. If you set `window.noZensmooth` to a non-falsy value (see [above](#disablingautomaticsmoothingonlocallinks)).
1512. In new browsers if the `scroll-behavior` CSS property is set to `smooth` on the `body` (see [above](#enablingnativesmooth-scrollinginthebrowser)). In this case Zenscroll will only enable automatic smooth-scrolling in browsers which don’t support this feature yet (e.g., Internet Explorer).
152
153#### 1.6. Exclude a link from the automatic smooth-scrolling
154
155If you want only some of the links to be excluded from the automatic smoothing then do one of the following:
156
1571. Add the class `noZensmooth` to the anchor element, for example `<a href="#about" class="noZensmooth">`
1581. Alternatively, start with the path of the page. E.g., instead of writing `<a href="#about">` use `<a href="/#about">` or `<a href="index.html#about">`.
159
160
161### 2. Scroll to the top of an element
162
163````js
164var about = document.getElementById("about")
165zenscroll.to(about)
166````
167
168Note that Zenscroll intentionally leaves a few pixels (by default 9px) from the edges of the screen or scrolling container. If you have a fixed navigation bar or footer bar then you probably need more than that. Or you may want to set it to zero. You can globally override the default value by calling `zenscroll.setup()` (see [below](#9.changesettings)), or by providing the `edgeOffset` parameter when you create a scroller for a DIV, e.g., `zenscroll.createScroller(myDiv, null, 20)`
169
170
171### 3. Scroll to a specific vertical position
172
173````js
174zenscroll.toY(50)
175````
176
177
178### 4. Scroll an element into view
179
180If the element is already fully visible, with the edge offset at the top and bottom, then no scroll is performed. Otherwise Zenscroll will try to make both top & bottom of element visible, if possible. If the element is higher than the visible viewport then it will simply scroll to the top of the element, including the edge offset.
181
182````js
183zenscroll.intoView(image1)
184````
185
186Tip: If you resize an element with a transition of 500ms, you can postpone calling zenscroll with that amount of time:
187
188````js
189image.classList.remove("is-small")
190setTimeout(function () {
191 zenscroll.intoView(image2)
192}, 500)
193````
194
195
196### 5. Scrolls the element to the center of the screen
197
198````js
199zenscroll.center(image2)
200````
201
202If you want you can also define an offset. The top of the element will be upwards from the center of the screen by this amount of pixels. (By default offset is the half of the element’s height.)
203
204````js
205var duration = 500 // milliseconds
206var offset = 200 // pixels
207zenscroll.center(image2, duration, offset)
208````
209
210Note that a zero value for offset is ignored. You can work around this by using `zenscroll.toY()`.
211
212
213### 6. Set the duration of the scroll
214
215The default duration is 999 which is ~1 second. The duration is automatically reduced for elements that are very close. You can specifically set the duration for each scroll function via an optional second parameter. If you pass a value of zero then the scroll happends immediately, without smoothing.
216
217Examples:
218
219````js
220zenscroll.toY(50, 100) // 100ms == 0.1 second
221````
222
223````js
224zenscroll.to(about, 500) // 500ms == half a second
225````
226
227````js
228zenscroll.center(image2, 2000) // 2 seconds
229````
230
231````js
232zenscroll.to(about, 0) // 0 milliseconds == no smoothing
233````
234
235
236### 7. Scroll inside a scrollable DIV
237
238Anything you can do within the document you can also do inside a scrollable DIV or other element. You just need to instantiate a new scroller for that element. I will also fall back by default to the native browser smooth-scrolling if available (which can be overridden via `setup()`).
239
240**Important:** the container DIV must have its `position` CSS property set to `relative`, `absolute` or `fixed`. If you want to keep it in the normal document flow, just assign `position: relative` to it via a class or a `style` attribute, like in the example below:
241
242````html
243<div id="container" style="position: relative">
244 <div id="item1">ITEM 1</div>
245 <div id="item2">ITEM 2</div>
246 <div id="item3">ITEM 3</div>
247 <div id="item4">ITEM 4</div>
248 <div id="item5">ITEM 5</div>
249 <div id="item6">ITEM 6</div>
250 <div id="item7">ITEM 7</div>
251</div>
252
253<script>
254 var defaultDuration = 500
255 var edgeOffset = 30
256 var myDiv = document.getElementById("container")
257 var myScroller = zenscroll.createScroller(myDiv, defaultDuration, edgeOffset)
258 var target = document.getElementById("item4")
259 myScroller.center(target)
260</script>
261````
262
263Obviously you can use all other scroll functions and parameters with the scrollable container. Two more examples:
264
265````js
266myScroller.toY(500)
267````
268
269````js
270myScroller.intoView(target)
271````
272
273
274### 8. Execute something when the scrolling is done
275
276You can provide a callback function to all four scroll functions, which is executed when the scroll operation is finished. For example, you change some UI elements but first you want to make sure that the relevant elements are visible.
277
278Note that the callback is immediately invoked if the native scroll-smoothing is enabled (see [above](#enablingnativesmooth-scrollinginthebrowser)).
279
280If you look at the source code of the examples under [Scroll inside a scrollable DIV](#7.scrollinsideascrollablediv) they are actually implemented like this:
281
282````js
283// Last line of example 1:
284zenscroll.intoView(container, 100, function () { myScroller.center(target) })
285
286// Example 2:
287zenscroll.intoView(container, 100, function () { myScroller.toY(35) })
288
289// Example 3:
290zenscroll.intoView(container, 100, function () { myScroller.intoView(target) })
291````
292
293So first the container (with _ITEM 1_ to _ITEM 7_) is scrolled into view if necessary, and then the scrolling inside the container is performed. Try scrolling out the above container and then hit one of the ‘Play’ buttons above to see how it works.
294
295This works with all four scrolling functions. The `onDone` parameter is always the last parameter:
296
2971. `to(element, duration, onDone)`
2981. `toY(y, duration, onDone)`
2991. `intoView(element, duration, onDone)`
3001. `center(element, duration, offset, onDone)`
301
302
303### 9. Change settings
304
305It’s easy to change the basic parameters of scrolling:
306
307- You can set the default value for duration. This will be valid for internal scrolls and all your direct scroll calls where you don’t specify a duration.
308- Change the edge offset (the spacing between the element and the screen edge). If you have a fixed navigation bar or footer bar then set the offset to their height.
309
310````js
311var defaultDuration = 777 // ms
312var edgeOffset = 42 // px
313zenscroll.setup(defaultDuration, edgeOffset)
314````
315
316You can change custom scrollers similarly:
317
318````js
319myScroller.setup(500, 10)
320````
321
322If you don’t want to change a value just omit the parameter or pass `null`. For example, the line below sets the default duration, while leaving other settings unchanged:
323
324````js
325zenscroll.setup(777) // only updates defaultDuration to 777
326````
327
328Sets the the spacing between the edge of the screen (or a DIV) and the target element you are scrolling to, while leaving the default duration unchanged:
329
330````js
331zenscroll.setup(null, 42) // only updates edgeOffset to 42
332````
333
334The function always returns the current values in an object, so even if no parameters are passed you can obtain the current settings:
335
336````js
337var currentSettings = zenscroll.setup()
338var dd = currentSettings.defaultDuration
339var eo = currentSettings.edgeOffset
340````
341
342
343
344### 10. Additional functions
345
346To check whether a scroll is being performed right now:
347
348````js
349var isScrolling = zenscroll.moving()
350````
351
352To stop the current scrolling:
353
354````js
355zenscroll.stop()
356````
357
358To get the current vertical scrolling position:
359
360````js
361var bodyY = zenscroll.getY()
362
363var myDivY = myDivScroller.getY()
364````
365
366To get the top position of an element within the body or a scroller:
367
368````js
369var myElemY = zenscroll.getTopOf(myElem)
370
371var relativeTopOfElem = myDivScroller.getTopOf(anElemInMyDiv)
372````
373
374Impotant: the returned value is without edge offset, and without recurcursively calculating nested scrollable containers.
375
376
377## License
378
379[Public Domain](http://unlicense.org). You can do with it whatever you want and I am not responsible for anything.
380
381
382
383## Other projects by me:
384
385- [Zenfonts](https://github.com/zengabor/zenfonts), a tiny JavaScript helper for @font-face web font loading.
386- [Zenvite.com](http://zenvite.com/): Create invitation pages & get everybody on the same page.
387
Note: See TracBrowser for help on using the repository browser.