Pageable transforms a web page into a full page scrolling presentation.
- Lightweight (less than 3kb gzipped)
- Responsive
- Performant
- Touch support
- Easy to set up
- Playground
- Adding progress bars
- Infinite Scrolling
- Infinite Slideshow
- Fun with delays
- Full-page image gallery
npm install pageable --save
Grab the file from one of the CDNs and include it in your page:
https://unpkg.com/pageable@latest/dist/pageable.js
You can replace latest with the required release number if needed.
You can also include the optional stylesheet that applies styling to the nav pips and buttons:
https://unpkg.com/pageable@latest/dist/pageable.css
Define a container element that has at least one descendant element with the data-anchor attribute.
<div id="container">
<div data-anchor="Page 1"></div>
<div data-anchor="Page 2"></div>
<div data-anchor="Page 3"></div>
<div data-anchor="Page 4"></div>
....
</div>Instantiate Pageable and pass a reference to the container in the constructor:
new Pageable("#container");The HTML will be transformed in the following way:
<div class="pg-wrapper">
<div id="container" class="pg-container">
<!-- pages -->
<div data-anchor="page-1" id="page-1" class="pg-page pg-active"></div>
<div data-anchor="page-2" id="page-2" class="pg-page"></div>
<div data-anchor="page-3" id="page-3" class="pg-page"></div>
<div data-anchor="page-4" id="page-4" class="pg-page"></div>
...
</div>
<!-- pips will go here -->
</div>If pips are enabled, their HTML will be appended to the .pg-wrapper element after the .pg-container element.
The defined anchors will be 'slugified' and used as the page's id - e.g. My Page 1 will be converted to my-page-1
Take care not to have another element with a duplicate id
You can pass an object as the second paramater to customise the instance:
new Pageable("#container", {
pips: true, // display the pips
animation: 300, // the duration in ms of the scroll animation
delay: 0, // the delay in ms before the scroll animation starts
throttle: 50, // the interval in ms that the resize callback is fired
orientation: "vertical", // or horizontal
swipeThreshold: 50, // swipe / mouse drag distance (px) before firing the page change event
freeScroll: false, // allow manual scrolling when dragging instead of automatically moving to next page
navPrevEl: false, // define an element to use to scroll to the previous page (CSS3 selector string or Element reference)
navNextEl: false, // define an element to use to scroll to the next page (CSS3 selector string or Element reference)
infinite: false, // enable infinite scrolling (from 0.4.0)
slideshow: { // enable slideshow that cycles through your pages automatically (from 0.4.0)
interval: 3000, // time in ms between page change,
delay: 0 // delay in ms after the interval has ended and before changing page
},
events: {
wheel: true, // enable / disable mousewheel scrolling
mouse: true, // enable / disable mouse drag scrolling
touch: true, // enable / disable touch / swipe scrolling
},
easing: function(currentTime, startPos, endPos, interval) {
// the easing function used for the scroll animation
return -endPos * (currentTime /= interval) * (currentTime - 2) + startPos;
},
onInit: function() {
// do something when the instance is ready
},
onUpdate: function() {
// do something when the instance updates
},
onBeforeStart: function() {
// do something before scrolling begins
},
onStart: function() {
// do something when scrolling begins
},
onScroll: function() {
// do something during scroll
},
onFinish: function() {
// do something when scrolling ends
},
});Any anchor on your page that has a hash that matches the ones in the current Pageable instance will trigger scrolling. This allows you to add navigation links without needing to define event listeners or callbacks to get them to trigger a scroll.
Displays the navigation pips.
Sets the scroll animation duration. Set to 0 to disable animation.
NOTE: This option was known as interval in versions prior to v0.5.0
Sets the delay in ms before the scroll animation starts.
Sets the swipe / mouse drag distance in px before firing the page change event. If drag / swipe distance is below this threshold then scrolling will not activate.
Sets the ability to drag / scroll freely instead of snapping to the next page.
Allow seamless continuous scrolling.
Sets the orientation of the instance. Either 'vertical' or 'horizontal'.
Sets the interval in ms that the resize callback is fired.
Define an element to use to scroll to the previous page. A valid CSS3 selector string or Element reference.
Define an element to use to scroll to the next page. A valid CSS3 selector string or Element reference.
Enables the slideshow function that cycles through your pages automatically.
The object has two properties to further customise the slidewhow:
interval- length of time inmsto display each page.delay- delay inmsafter the interval has ended and before changing page.
Define the allowed events.
wheel- enable / disable mousewheel scrollingmouse- enable / disable mouse drag scrollingtouch- enable / disable touch / swipe scrolling
All propertied are set to true by default.
Define the easing function used for the scroll animation.
The function takes four arguments:
function(currentTime, startPos, endPos, interval) {
// the default easing function
return -endPos * (currentTime /= interval) * (currentTime - 2) + startPos;
}
currentTime- The current time inmsstartPos- The start position inpxendPos- The end position inpxinterval- The duration of the animation inms
Define a callback to be called when the instance is fully rendered and ready for use.
The function takes a single argument that returns the data object (See Custom Events)
new Pageable("#container", {
onInit: function(data) {
// data.index, data.scrolled, data.max
}
});Define a callback to be called when the instance updates.
The function takes a single argument that returns the data object (See Custom Events)
Define a callback to be called before scrolling begins.
The function takes a single argument that returns the data object (See Custom Events)
Define a callback to be called when scrolling begins.
The function takes a single argument that returns the data object (See Custom Events)
Define a callback to be called while scrolling.
The function takes a single argument that returns the data object (See Custom Events)
Define a callback to be called when scrolling finishes.
The function takes a single argument that returns the data object (See Custom Events)
Destroy the instance.
This will remove all event listeners and return the DOM to it's initial state.
pageable.destroy();Initialise the instance after destroying.
pageable.init();Scroll to next page.
pageable.next();Scroll to previous page.
pageable.prev();Scroll to defined page number.
// scroll to page 3
pageable.scrollToPage(3);Scroll to defined anchor.
pageable.scrollToAnchor("#myanchor");Orientate the instance to either vertical or horizontal.
pageable.orientate("horizontal");
// or
pageable.orientate("vertical");Returns an instance of the slideshow. This requires the slideshow option to be set to true (v0.4.0 and above).
The sideshow instance has two methods:
start()- starts / resumes the slideshowstop()- stops / pauses the slideshow
// stop / pause slideshow
pageable.slideshow().stop();
// start / resume slideshow
pageable.slideshow().start();Add custom event listener. See Custom Events
remove custom event listener. See Custom Events
You can listen to Pageable's custom events with the on(type, callback) method.
The callback has one argument which returns the data object:
{
index: // the current page index
scrolled: // the current scroll offset
max: // the maximum scroll amount possible
}You can calculate the progress of the instance from the data:
const percentage = data.scrolled / data.max * 100;This can be helpful when adding progress indicators (see Adding Progress Bars).
const pages = new Pageable("#container");
pages.on("init", data => {
// do something when the instance is ready
});
pages.on("update", data => {
// do something when the instance is updated
// this event also fires when the screen size changes
});
pages.on("scroll.before", data => {
// do something before scrolling starts
// this event will fire when the defined delay begins
// e.g. if the delay is set to 400, this event will
// fire 400ms BEFORE the "scroll.start" event fires
});
pages.on("scroll.start", data => {
// do something when scrolling starts
// this event will fire when the defined delay ends
// e.g. if the delay is set to 400, this event will
// fire 400ms AFTER the "scroll.before" event fires
});
pages.on("scroll", data => {
// do something during scroll
});
pages.on("scroll.end", data => {
// do something when scrolling ends
});Copyright © 2018 Karl Saunders | BSD & MIT license