repository·master·Indexed 18 days ago
https://github.com/mobius1/pageableA lightweight (<3kb gzipped), responsive JavaScript library for creating full-page scrolling web presentations. It transforms standard web pages into scrolling presentations with touch, keyboard, and mouse wheel support without requiring jQuery. Features include customizable orientations (vertical/horizontal), navigation pips, infinite scrolling, a slideshow mode, and a comprehensive API for programmatic control and lifecycle callbacks.
<a href="#page-1"> links for navigation without writing custom event listeners.You can include Pageable directly in your HTML by grabbing the files from a CDN.
Include the JavaScript file:
<script src="https://unpkg.com/pageable@latest/dist/pageable.min.js"></script>Optionally, include the stylesheet to apply default styling to navigation pips and buttons:
<link rel="stylesheet" href="https://unpkg.com/pageable@latest/dist/pageable.min.css">You can replace latest with a specific version number if required.
<script src="https://unpkg.com/pageable@latest/dist/pageable.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/pageable@latest/dist/pageable.min.css">To add Pageable to your project using npm, run the following command:
npm install pageable --savePageable transforms a web page into a full-page scrolling presentation. To set it up:
data-anchor attribute.Pageable instance and pass a reference to the container (e.g., a CSS selector string).Note on Anchors: The values provided in data-anchor will be 'slugified' and used as the element's id. For example, data-anchor="Page 1" becomes id="page-1". If you do not use data-anchor attributes, you must manually define the anchors using the anchors option in the constructor.
<!-- HTML Setup -->
<div id="container">
<div data-anchor="Page 1"></div>
<div data-anchor="Page 2"></div>
<div data-anchor="Page 3"></div>
</div>// JS Setup
new Pageable("#container");If you enable the slideshow option, Pageable will automatically transition through pages at a set interval.
To use it, pass a configuration object to the slideshow key in your main options. The slideshow uses an interval (how often to move) and a delay (how long to wait after the move starts before the next transition). If infinite is enabled in the main config, the slideshow will loop.
interval: Time in ms between transitions.delay: Time in ms to wait before executing the transition.onBeforeStart: Callback triggered before each slide change.const pg = new Pageable('#container', {
infinite: true,
slideshow: {
interval: 5000,
delay: 100,
onBeforeStart: (index) => console.log('Starting slide:', index)
}
});
// Access the slideshow instance
const slider = pg.slideshow();
slider.start();
slider.stop();You can customize the behavior of your Pageable instance by passing an options object as the second argument to the constructor.
Key configuration categories include:
childSelector (CSS selector for pages), anchors (array of anchor names).pips (boolean to show navigation dots), animation (duration in ms), easing (custom easing function).orientation ("vertical" or "horizontal"), swipeThreshold (px distance for swipe/drag), freeScroll (boolean), events (toggle wheel, mouse, touch, or keydown navigation).navPrevEl and navNextEl (selectors/elements for custom prev/next buttons), infinite (boolean for infinite scrolling).slideshow (object with interval and delay for automatic cycling).onInit, onUpdate, onBeforeStart, onStart, onScroll, onFinish.new Pageable("#container", {
childSelector: "[data-anchor]",
anchors: [],
pips: true,
animation: 300,
delay: 0,
throttle: 50,
orientation: "vertical",
swipeThreshold: 50,
freeScroll: false,
navPrevEl: false,
navNextEl: false,
infinite: false,
slideshow: {
interval: 3000,
delay: 0
},
events: {
wheel: true,
mouse: true,
touch: true,
keydown: true
},
easing: function(currentTime, startPos, endPos, interval) {
return -endPos * (currentTime /= interval) * (currentTime - 2) + startPos;
},
onInit: function() { /* ... */ },
onUpdate: function() { /* ... */ },
onBeforeStart: function() { /* ... */ },
onStart: function() { /* ... */ },
onScroll: function() { /* ... */ },
onFinish: function() { /* ... */ }
});When initializing a new Pageable instance, you can pass an options object to customize behavior. Key options include:
childSelector (Boolean, default: true): CSS3 selector for nodes used as pages.anchors (Array): Array of strings for page anchors. Must match the number of pages.pips (Boolean, default: true): Toggle navigation pips.animation (Number, default: 300): Scroll animation duration in ms. Set to 0 to disable.delay (Number, default: 0): Delay in ms before scroll animation starts.swipeThreshold (Number, default: 50): Min distance in px for swipe/drag to trigger page change.freeScroll (Boolean, default: false): Allows free dragging instead of snapping.infinite (Boolean, default: false): Enables continuous seamless scrolling.orientation (String, default: 'vertical'): Set to 'vertical' or 'horizontal'.navPrevEl / navNextEl (String|HTMLElement): CSS selector or Element for previous/next navigation.slideshow (Object): Enables automatic cycling. Properties: interval (ms per page) and delay (ms before change).events (Object): Enable/disable wheel, mouse, touch, or keydown navigation.easing (Function): Custom easing function for scroll animation.onInit, onUpdate, onBeforeStart, onStart, onScroll, onFinish (Functions): Lifecycle callbacks.Pageable provides several lifecycle hooks that you can define in the configuration object. These functions receive a data object containing the current state:
{
index: // current page index
scrolled: // current scroll offset
max: // maximum scroll amount possible
percent: // scroll position as a percentage (v0.6.7+)
}Available hooks:
onInit: Called when the instance is fully rendered and ready.onUpdate: Called when the instance updates (including screen resize).onBeforeStart: Called before scrolling begins (after the configured delay).onStart: Called when scrolling begins.onScroll: Called during the scroll process.onFinish: Called when scrolling finishes.new Pageable("#container", {
onInit: function(data) {
// data.index, data.scrolled, data.max
}
});You can attach custom event listeners using the .on(type, callback) method. The callback receives a data object with index, scrolled, max, and percent properties.
Common event types include:
initupdatescroll.before (fires when the defined delay begins)scroll.start (fires when the defined delay ends)scroll (fires during scroll)scroll.end (fires when scrolling ends)const pages = new Pageable("#container");
pages.on("init", data => {
// do something when the instance is ready
});
pages.on("scroll.before", data => {
// fires when the delay begins
});
pages.on("scroll.start", data => {
// fires when the delay ends
});If you want to customize the scroll animation feel, provide an easing function in the options. The function is called with four arguments:
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.Example of a default easing implementation:
function(currentTime, startPos, endPos, interval) {
// the default easing function
return -endPos * (currentTime /= interval) * (currentTime - 2) + startPos;
}The Pageable instance provides several methods to programmatically control the view and instance state:
destroy(): Removes all event listeners and returns the DOM to its initial state.init(): Re-initializes the instance after it has been destroyed.next(): Scrolls to the next page.prev(): Scrolls to the previous page.scrollToPage(page): Scrolls to a specific page number.scrollToAnchor(anchor): Scrolls to a specific anchor string (e.g., "#myanchor").orientate(orientation): Changes orientation to 'vertical' or 'horizontal'.slideshow(): Returns the slideshow instance (requires slideshow: true in options). Use .start() and .stop() on the returned object.on(event, callback): Adds a custom event listener.off(event, callback): Removes a custom event listener.// Navigation
pageable.next();
pageable.prev();
pageable.scrollToPage(3);
pageable.scrollToAnchor("#myanchor");
// Slideshow control
pageable.slideshow().start();
pageable.slideshow().stop();
// Orientation
pageable.orientate("horizontal");To create a full-page scrolling presentation, instantiate the Pageable class by passing a container element (or a CSS selector string) and an optional configuration object. Pageable will automatically wrap your container, manage page transitions, and handle navigation via mouse wheel, touch, or keyboard.
// Using a selector
const pg = new Pageable('#my-container', {
orientation: 'vertical',
infinite: true
});
// Using a DOM element
const container = document.querySelector('.my-container');
const pg = new Pageable(container, {
orientation: 'horizontal'
});