Mobius1 / Pageable
Programming Languages
Projects that are alternatives of or similar to Pageable
Pageable
Pageable transforms a web page into a full page scrolling presentation.
- Lightweight (less than 3kb gzipped)
- Responsive
- Performant
- Touch support
- Easy to set up
- IE10+
Demos
- Playground
- Adding progress bars
- Infinite Scrolling
- Infinite Slideshow
- Fun with delays
- Full-page image gallery
If this project helps you then you can grab me a coffee or beer to say thanks.
Contents
Install
npm
npm install pageable --save
Browser
Grab the file from one of the CDNs and include it in your page:
https://unpkg.com/[email protected]/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/[email protected]/dist/pageable.min.css
Set up
Define a container element that has at least one descendant element with the data-anchor attribute.
HTML
<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:
JS
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 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:
JS
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
},
});
Anchors
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
childSelector
type: Boolean
default: true
A CSS3 selector string for selecting the nodes to be used as pages
anchors
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.
pips
type: Boolean
default: true
Displays the navigation pips.
animation
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
delay
type: Number
default: 0
Sets the delay in ms before the scroll animation starts.
swipeThreshold
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.
freeScroll
type: Boolean
default: false
Sets the ability to drag / scroll freely instead of snapping to the next page.
infinite
type: Boolean
default: false
Allow seamless continuous scrolling.
orientation
type: String
default: 'vertical'
Sets the orientation of the instance. Either 'vertical' or 'horizontal'.
throttle
type: Number
default: 50
Sets the interval in ms that the resize callback is fired.
navPrevEl
type: String|HTMLElement
default: false
Define an element to use to scroll to the previous page. A valid CSS3 selector string or Element reference.
navNextEl
type: String|HTMLElement
default: false
Define an element to use to scroll to the next page. A valid CSS3 selector string or Element reference.
slideshow
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 inmsto display each page. -
delay- delay inmsafter the interval has ended and before changing page.
events
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.
easing
type: Function
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 inms -
startPos- The start position inpx -
endPos- The end position inpx -
interval- The duration of the animation inms
onInit
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)
new Pageable("#container", {
onInit: function(data) {
// data.index, data.scrolled, data.max
}
});
onUpdate
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)
onBeforeStart
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)
onStart
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)
onScroll
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)
onFinish
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
destroy()
Destroy the instance.
This will remove all event listeners and return the DOM to it's initial state.
pageable.destroy();
init()
Initialise the instance after destroying.
pageable.init();
next()
Scroll to next page.
pageable.next();
prev()
Scroll to previous page.
pageable.prev();
scrollToPage([page])
Scroll to defined page number.
// scroll to page 3
pageable.scrollToPage(3);
scrollToAnchor([anchor])
Scroll to defined anchor.
pageable.scrollToAnchor("#myanchor");
orientate([orientation])
Orientate the instance to either vertical or horizontal.
pageable.orientate("horizontal");
// or
pageable.orientate("vertical");
slideshow()
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
// stop / pause slideshow
pageable.slideshow().stop();
// start / resume slideshow
pageable.slideshow().start();
on([event, [callback]])
Add custom event listener. See Custom Events
off([event, [callback]])
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:
{
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).
Examples
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
});
If this project helps you then you can grab me a coffee or beer to say thanks.
Copyright © 2018 Karl Saunders | BSD & MIT license