Description
Pageable transforms a web page into a full page scrolling presentation.
- Lightweight (less than 3kb gzipped)
- Responsive
- Performant
- Touch support
- Easy to set up
Pageable alternatives and similar libraries
Based on the "Scroll" category.
Alternatively, view Pageable alternatives based on common mentions on social networks and blogs.
-
fullPage
fullPage plugin by Alvaro Trigo. Create full screen pages fast and simple -
skrollr
Stand-alone parallax scrolling library for mobile (Android + iOS) and desktop. No jQuery. -
parallax
Parallax Engine that reacts to the orientation of a smart device -
iscroll
iScroll is a high performance, small footprint, dependency free, multi-platform javascript scroller. -
ScrollMagic
The javascript library for magical scroll interactions. -
onepage-scroll
Create an Apple-like one page scroller website (iPhone 5S website) with One Page Scroll plugin -
headroom
Give your pages some headroom. Hide your header until you need it -
vue-virtual-scroller
⚡️ Blazing fast scrolling for any amount of data -
Clusterize.js
Tiny vanilla JS plugin to display large data sets easily -
locomotive-scroll
🛤 Detection of elements in viewport & smooth scrolling with parallax. -
elevator.js
Finally, a "back to top" button that behaves like a real elevator. -
scrollMonitor
A simple and fast API to monitor elements as you scroll -
simpleParallax
Simple and tiny JavaScript library that adds parallax animations on any images -
angular-infinite-list
A short and powerful infinite scroll list library for angular, with zero dependencies
Appwrite - The Open Source Firebase alternative introduces iOS support
* Code Quality Rankings and insights are calculated and provided by Lumnify.
They vary from L1 to L5 with "L5" being the highest.
Do you think we are missing an alternative of Pageable or a related project?
README
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
- Getting Started
- API
- Options
- childSelector
- anchors
- pips
- animation
- delay
- throttle
- orientation
- swipeThreshold
- freeScroll
- navPrevEl
- navNextEl
- infinite
- easing
- events
- onInit
- onUpdate
- onBeforeStart
- onStart
- onScroll
- onFinish
- Methods
- destroy()
- init()
- next()
- prev()
- scrollToPage()
- scrollToAnchor()
- orientate()
- slideshow()
- on()
- off()
* Custom Events
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 inms
to display each page.delay
- delay inms
after the interval has ended and before changing page.
events
type: Object
Define the allowed events.
wheel
- enable / disable mousewheel scrollingmouse
- enable / disable mouse drag scrollingtouch
- enable / disable touch / swipe scrollingkeydown
- 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 slideshowstop()
- 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
*Note that all licence references and agreements mentioned in the Pageable README section above
are relevant to that project's source code only.