Simple JavaScript plugin to manage sliders using CSS Scroll Snap.
npm install @tannerhodges/snap-slider
import SnapSlider from '@tannerhodges/snap-slider';
-- OR --<script async src="snap-slider.min.js"></script>
- Add
data-snap-slider
to your elements.
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 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>
data-snap-slider="<ID>"
- Container. Create a slider for this container element. Should have CSSposition: relative
,overflow: scroll
, andscroll-snap-type
defined.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),
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-align
to calculate its scroll position, but older browsers fail to return this value. If you need to supportcenter
orend
alignments 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 initsbutton
s 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.
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': () => {},
},
}
);
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.?
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 likeprev
andnext
). 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
, andnext
to 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
, andnext
to 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 internalslides
array, 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
prev
ornext
we'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
SnapSlider.get(id)
- Get theSnapSlider
object for a slider based on its ID.SnapSlider.debug([idOrElements])
-console.log
info about a slider, its nav, or goto buttons.
Element.SnapSlider
- After a slider is intialized, you can access itsSnapSlider
instance by getting the element'sSnapSlider
property. For example,document.querySelector('.example').SnapSlider
.
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!
TODO: Examples