tannerhodges🥨 Snap Slider
Simple JavaScript plugin to manage sliders using CSS Scroll Snap.
⚡️ Quick Start
npm install @tannerhodges/snap-sliderimport SnapSlider from '@tannerhodges/snap-slider';-- OR --<script async src="snap-slider.min.js"></script>- Add
data-snap-sliderto your elements.
📖 Outline
🤔 Why?
CSS Scroll Snap makes sliders as simple as a few lines of CSS, but you still need JavaScript for things like buttons and event handlers.
Snap Slider makes that as easy as adding a data-snap-slider attribute.
👉 For a full explanation & demos, check out the docs.
⚙️ Install
- Install the package.
npm install @tannerhodges/snap-slider- Import the package into your application script.
import SnapSlider from '@tannerhodges/snap-slider';Or, if you prefer, include the script in your HTML.
<script async src="snap-slider.min.js"></script>- Add data attributes to your CSS sliders.
<ul class="slider" data-snap-slider="example">
<li class="slide">...</li>
<li class="slide">...</li>
<li class="slide">...</li>
<li class="slide">...</li>
</ul>
<ul class="slider-nav" data-snap-slider-nav="example">
<li><button type="button">Previous</button></li>
<li><button type="button">1</button></li>
<li><button type="button">2</button></li>
<li><button type="button">3</button></li>
<li><button type="button">4</button></li>
<li><button type="button">Next</button></li>
</ul>👨🏫 HTML API
Elements
data-snap-slider="<ID>"- Container. Create a slider for this container element. Should have CSSposition: relative,overflow: scroll, andscroll-snap-typedefined.data-snap-slider-nav="<ID>"- Nav. Wrap around a group of buttons to specify which slider they control.data-snap-slider-goto="<SLIDE>"- "Goto" Button. Tell a button which slide it should go to. (Can target specific sliders using<ID>:<SLIDE>syntax.)- Possible values: Numbers (starting at 1),
first,middle,last,prev,next.
- Possible values: Numbers (starting at 1),
Options
data-snap-slider-slides- By default, Snap Slider assumes all the container's children are slides. If you have non-slide elements in your slider, add this attribute to the container to specify which elements should be treated as slides.data-snap-slider-align="<ALIGN>"- Snap Slider checks each slide's CSSscroll-snap-alignto calculate its scroll position, but older browsers fail to return this value. If you need to supportcenterorendalignments in Internet Explorer, add this attribute to a container or slide to specify its alignment.- Possible values:
start,end, orcenter.
- Possible values:
data-snap-slider-start="<SLIDE>"- Sliders start on slide 1 by default. Add this attribute to a container to specify a different slide to start on.- Possible values: Numbers (starting at 1),
first,middle,last.
- Possible values: Numbers (starting at 1),
data-snap-slider-loop="<BOOLEAN>"- Previous/next buttons are disabled on the first/last slides by default. Add this attribute to a container to enable them to loop around to the other end of the slider (e.g., clicking a previous button on slide 1 will goto the last slide).data-snap-slider-buttons="<SELECTOR>"- Snap Slider automatically initsbuttons in nav elements as goto buttons. Add this attribute to a container or nav to specify which elements should be treated as goto buttons.data-snap-slider-prev="<SELECTOR>"- Snap Slider tries to detect previous buttons based on their content and class names (e.g., if the text or class contains the string "prev"). Add this attribute to a container or nav to target a custom selector for previous buttons.data-snap-slider-next="<SELECTOR>"- Snap Slider tries to detect next buttons based on their content and class names (e.g., if the text or class contains the string "next"). Add this attribute to a container or nav to target a custom selector for next buttons.
🤖 JavaScript API
Constructor
const slider = new SnapSlider(
// `container` - This is the slider's container element.
// You can pass in a string selector, Element, NodeList, or jQuery object.
container,
// `options` - This object extends the default settings.
{
// `options.id` - String ID for this slider.
// Use this to associate containers, navs, and goto buttons.
// If empty, defaults to `container.children`.
id: '',
// `options.slides` - String selector to target slide elements.
// Useful if you have non-slide elements in your container.
// If empty, defaults to `container.children`.
slides: '',
// `options.align` - String to specify fallback alignment for older browsers.
// Mimics `scroll-snap-align` for browsers that don't support CSS Scroll Snap.
align: '',
// `options.nav` - String selector to target nav elements.
// Looks for matches across the whole document.
nav: '',
// `options.buttons` - String selector to target goto buttons.
// Looks for matches in container and nav elements.
buttons: '',
// `options.prev` - String selector to target previous buttons.
// Looks for matches in container and nav elements.
prev: '',
// `options.next` - String selector to target next buttons.
// Looks for matches in container and nav elements.
next: '',
// `options.start` - Number or string alias to change which slide is current on load.
// Accepts any valid goto alias (numbers starting at 1, `first`, `middle`, `last`).
start: 1,
// `options.loop` - Boolean to enable prev/next buttons to loop around to the other end of the slider.
loop: false,
// `options.on` - Object to add callbacks for different events.
on: {
'load': () => {},
'change': () => {},
'change.click': () => {},
'change.scroll': () => {},
'change.keydown': () => {},
'change.focusin': () => {},
'scroll': () => {},
'scroll.start': () => {},
'scroll.end': () => {},
},
}
);Properties
align- What's this slider's CSSscroll-snap-align?callbacks- Functions to fire for each slider event.container- Container element.current- Index of current slide. Values start at 1.id- Slider ID.loop- Boolean. Should slide loop or not?options- Slider options (default values + custom overrides).scrolling- Boolean. Is the slider scrolling at this moment?slides- Array of slides.transition- Object. Are we in the middle of a transition? Where from, to, etc.?
Instance Methods
getSlide(index)- Get a specific slide element. Accepts any valid goto alias.getCurrentSlide()- Get the current slide element.goto(index, [options])- Go to a slide.- Goto Aliases - Numbers (starting at 1),
first,middle,last,prev,next. options.focus- By default, we focus slides when you go to them (except for relative changes likeprevandnext). Use this option to disable the default focus handling.options.force- Force-update the scroll position, even if we're already on the current slide.options.ignoreCallbacks- Ignore custom callbacks for events.options.immediate- Immediately update position without smooth scrolling.
- Goto Aliases - Numbers (starting at 1),
addNav(containerOrOptions, [options])- Add a nav element for the current slider. Automatically hooks up any nav buttons inside the nav.options.container- The nav element. Defaults tocontainerOrOptions. Limits the query forbuttons,prev, andnextto be inside the nav container (instead of the whole document).options.buttons- String selector to target goto buttons inside the nav container. If empty, defaults tobutton.options.prev- String selector to target previous buttons inside the nav container.options.next- String selector to target next buttons inside the nav container.
addGotoButtons(buttonsOrOptions, [options])- Add goto buttons for the current slider.options.container- A parent nav element. If set, limits the query forbuttons,prev, andnextto be inside the nav container (instead of the whole document).options.buttons- String selector to target goto buttons. Defaults tobuttonsOrOptions.options.prev- String selector to target previous buttons.options.next- String selector to target next buttons.
update()- Update this slider (e.g., on resize). Basically just repositions the current slide.reset()- Reset this slider (e.g., after adding or removing a slide). Updates the slide elements, our internalslidesarray, and repositions the current slide.destroy()- Destroy this slider. Stop any active transitions, remove its event listeners, and delete it from our internal array of slider instances.on(event, callback)- Add callbacks to fire on specific events.change- Fires any time the current slide changes.change.click- Fires when a user clicks a goto button.change.scroll- Fires when a user scrolls to another slide.change.keydown- Fires when a user is focused inside the container and presses an arrow key to change the current slide (e.g., up, down, left, or right).change.focusin- Fires when a slide gains focus.- Note: For keyboard accessibility, we automatically focus the target slide whenever a user clicks a non-relative goto button. In other words, if you goto any index besides
prevornextwe'll auto-focus that slide.
- Note: For keyboard accessibility, we automatically focus the target slide whenever a user clicks a non-relative goto button. In other words, if you goto any index besides
Static Methods
SnapSlider.get(id)- Get theSnapSliderobject for a slider based on its ID.SnapSlider.debug([idOrElements])-console.loginfo about a slider, its nav, or goto buttons.
HTML Properties
Element.SnapSlider- After a slider is intialized, you can access itsSnapSliderinstance by getting the element'sSnapSliderproperty. For example,document.querySelector('.example').SnapSlider.
Example
import SnapSlider from '@tannerhodges/snap-slider';
// Create a new slider.
const slider = new SnapSlider('.example', {
id: 'example-slider',
nav: '.example-nav',
start: 'middle',
});
// The rest is up to you!
// 🏃♂️ Go make something!✍️ CodePen Examples
TODO: Examples