Create full page scrolling web pages. No jQuery.
npm install pageable
npm install pageable --save
`
---
$3
Grab the file from one of the CDNs and include it in your page:
`
https://unpkg.com/pageable@latest/dist/pageable.min.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.min.css
`
---
Set up
Define a container element that has at least one descendant element with the data-anchor attribute.
$3
`html
....
`
Instantiate Pageable and pass a reference to the container in the constructor:
$3
`javascript
new Pageable("#container");
`
The HTML will be transformed in the following way:
`html
...
`
If you don't set the [data-anchor] attribute then you must set the anchors with the anchors option.
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:
$3
`javascript
new Pageable("#container", {
childSelector: "[data-anchor]" // CSS3 selector string for the pages
anchors: [], // define the page anchors
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
keydown: true, // enable / disable keyboard navigation
},
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
},
});
`
---
$3
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.
---
API Reference
---
Options
$3
###### type: Boolean
###### default: true
A CSS3 selector string for selecting the nodes to be used as pages
---
$3
###### type: Array
###### default: undefined
An array of strings to use as the page anchors. Make sure the number of anchors used is equal to the number of pages.
---
$3
###### type: Boolean
###### default: true
Displays the navigation pips.
---
$3
###### type: Number
###### default: 300
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
---
$3
###### type: Number
###### default: 0
Sets the delay in ms before the scroll animation starts.
---
$3
###### type: Number
###### default: 50
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.
---
$3
###### type: Boolean
###### default: false
Sets the ability to drag / scroll freely instead of snapping to the next page.
---
$3
###### type: Boolean
###### default: false
Allow seamless continuous scrolling.
---
$3
###### type: String
###### default: 'vertical'
Sets the orientation of the instance. Either 'vertical' or 'horizontal'.
---
$3
###### type: Number
###### default: 50
Sets the interval in ms that the resize callback is fired.
---
$3
###### type: String|HTMLElement
###### default: false
Define an element to use to scroll to the previous page. A valid CSS3 selector string or Element reference.
---
$3
###### type: String|HTMLElement
###### default: false
Define an element to use to scroll to the next page. A valid CSS3 selector string or Element reference.
---
$3
###### type: Object
###### default: false
Enables the slideshow function that cycles through your pages automatically.
The object has two properties to further customise the slidewhow:
* interval - length of time in ms to display each page.
* delay - delay in ms after the interval has ended and before changing page.
---
$3
###### type: Object
Define the allowed events.
* wheel - enable / disable mousewheel scrolling
* mouse - enable / disable mouse drag scrolling
* touch - enable / disable touch / swipe scrolling
* keydown - enable / disable keyboard navigation
All properties are set to true by default.
---
$3
###### type: Function
Define the easing function used for the scroll animation.
The function takes four arguments:
`javascript
function(currentTime, startPos, endPos, interval) {
// the default easing function
return -endPos (currentTime /= interval) (currentTime - 2) + startPos;
}
`
* currentTime - The current time in ms
* startPos - The start position in px
* endPos - The end position in px
* interval - The duration of the animation in ms
---
$3
###### type: Function
###### default: noop
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)
`javascript
new Pageable("#container", {
onInit: function(data) {
// data.index, data.scrolled, data.max
}
});
`
---
$3
###### type: Function
###### default: noop
Define a callback to be called when the instance updates.
The function takes a single argument that returns the data object (See Custom Events)
---
$3
###### type: Function
###### default: noop
Define a callback to be called before scrolling begins.
The function takes a single argument that returns the data object (See Custom Events)
---
$3
###### type: Function
###### default: noop
Define a callback to be called when scrolling begins.
The function takes a single argument that returns the data object (See Custom Events)
---
$3
###### type: Function
###### default: noop
Define a callback to be called while scrolling.
The function takes a single argument that returns the data object (See Custom Events)
---
$3
###### type: Function
###### default: noop
Define a callback to be called when scrolling finishes.
The function takes a single argument that returns the data object (See Custom Events)
---
Methods
$3
Destroy the instance.
This will remove all event listeners and return the DOM to it's initial state.
`javascript
pageable.destroy();
`
---
$3
Initialise the instance after destroying.
`javascript
pageable.init();
`
---
$3
Scroll to next page.
`javascript
pageable.next();
`
---
$3
Scroll to previous page.
`javascript
pageable.prev();
`
---
$3
Scroll to defined page number.
`javascript
// scroll to page 3
pageable.scrollToPage(3);
`
---
$3
Scroll to defined anchor.
`javascript
pageable.scrollToAnchor("#myanchor");
`
---
$3
Orientate the instance to either vertical or horizontal.
`javascript
pageable.orientate("horizontal");
// or
pageable.orientate("vertical");
`
---
$3
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 slideshow
* stop() - stops / pauses the slideshow
`javascript
// stop / pause slideshow
pageable.slideshow().stop();
// start / resume slideshow
pageable.slideshow().start();
`
---
$3
Add custom event listener. See Custom Events
---
$3
remove custom event listener. See Custom Events
---
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:
`javascript
{
index: // the current page index
scrolled: // the current scroll offset
max: // the maximum scroll amount possible
percent: // the scroll position as a percentage of the maximum scroll (v0.6.7 and above)
}
`
The percent property can be helpful when adding progress indicators (see Adding Progress Bars).
$3
`javascript
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
});
``