@tannerhodges/snap-slider

# 🥨 Snap Slider Simple JavaScript plugin to manage sliders using [CSS Scroll Snap](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Scroll_Snap). ## ⚡️ Quick Start 1. `npm install @tannerhodges/snap-slider` 2. `import SnapSlider from '@tannerhodges/snap-slider';` _-- OR --_ `<script async src="snap-slider.min.js"></script>` 3. Add `data-snap-slider` to your elements. --- ## 📖 Outline - [Why?](#-why) - [Install](#%EF%B8%8F-install) - [HTML API](#-html-api) - [JavaScript API](#-javascript-api) - [CodePen Examples](#%EF%B8%8F-codepen-examples) - [Changelog](#-changelog) ## 🤔 Why? [CSS Scroll Snap](https://caniuse.com/#feat=css-snappoints) 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](https://tannerhodges.github.io/snap-slider/). [![](./screenshots/docs.png)](https://tannerhodges.github.io/snap-slider/) ## ⚙️ Install 1. Install the package. ```bash npm install @tannerhodges/snap-slider ``` 2. Import the package into your application script. ```js import SnapSlider from '@tannerhodges/snap-slider'; ``` Or, if you prefer, include the script in your HTML. ```html <script async src="snap-slider.min.js"></script> ``` 3. Add data attributes to your CSS sliders. ```html <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 CSS `position: relative`, `overflow: scroll`, and `scroll-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`. ### 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 CSS `scroll-snap-align` to calculate its scroll position, but older browsers fail to return this value. If you need to support `center` or `end` alignments in Internet Explorer, add this attribute to a container or slide to specify its alignment. - Possible values: `start`, `end`, or `center`. - `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`. - `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 inits `button`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. ## 🤖 JavaScript API ### Constructor ```js 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 CSS `scroll-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 like `prev` and `next`). 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. - `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 to `containerOrOptions`. Limits the query for `buttons`, `prev`, and `next` 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 to `button`. - `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 for `buttons`, `prev`, and `next` to be inside the nav container (instead of the whole document). - `options.buttons` - String selector to target goto buttons. Defaults to `buttonsOrOptions`. - `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 internal `slides` 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` or `next` we'll auto-focus that slide. ### Static Methods - `SnapSlider.get(id)` - Get the `SnapSlider` object for a slider based on its ID. - `SnapSlider.debug([idOrElements])` - `console.log` info about a slider, its nav, or goto buttons. ### HTML Properties - `Element.SnapSlider` - After a slider is intialized, you can access its `SnapSlider` instance by getting the element's `SnapSlider` property. For example, `document.querySelector('.example').SnapSlider`. ### Example ```js 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_ ## 📝 [Changelog](changelog.md)