react-use-snap-slider v0.1.3
react-use-snap-slider
This is simple React hook for creating a CSS Scroll Snap slider. It allows you to create basic sliders with a few lines of code, and gives you full control over the styling.
- Native scrolling and snapping
- Supports SSR, since all the layout is done in CSS - No JS layout calculations
- Uses React IntersectionObserver to detect when slides are visible
- MutationObserver to detect when slides are added or removed
It's still early. There are likely to be bugs and missing features.
Installation
npm install react-use-snap-sliderUsage
useSnapSlider hook
The useSnapSlider hook handles the logic for a CSS Scroll Snap slider.
import { useSnapSlider } from "react-snap-slider";
function App() {
const { ref, next, previous, activeIndex, totalSlides } = useSnapSlider({
threshold: 0,
});
return (
<div>
<div
ref={ref}
className="flex snap-x snap-mandatory overflow-x-scroll scrollbar-hide"
>
<div className="flex-none basis-full snap-start">Slide 1</div>
<div className="flex-none basis-full snap-start">Slide 2</div>
<div className="flex-none basis-full snap-start">Slide 3</div>
</div>
<p>
Slide {activeIndex + 1} / {totalSlides}
</p>
<button>Previous</button>
<button>Next</button>
</div>
);
}API
Options
Provide these values as the options argument in the useSnapSlider hook:
| Name | Type | Default | Description |
|---|---|---|---|
| selector | string | A CSS selector to use to find the slides inside the root element. If not defined, all children will be used | |
| threshold | number | 0 | Number between 0 and 1 indicating the percentage of a slide that should be visible, before it's considered visible. |
| disabled | boolean | false | Disable the snap slider logic |
| loop | boolean | true | Loop the slides with the next and previous functions. |
Return values
The useSnapSlider hook returns an object with the following values:
| Name | Type | Description |
|---|---|---|
| ref | Ref | The ref function to pass to the slider container. This is the element that can scroll to show the slides. |
| activeIndex | number | The index of the first visible slide. |
| totalSlides | number | The total number of slides that's been registered. This will be 0 until the ref is set. |
| next | () => void | A function to scroll to the next slide. |
| previous | () => void | A function to scroll to the previous slide. |
| scrollTo | (index: number) => void | A function to scroll to a specific slide. |
Styling
The useSnapSlider hook handles the logic for a snap slider, giving you full control over the styling.
Tailwind CSS
Example of a snap slider with three slides, styled with Tailwind CSS.
The important parts are:
snap-x snap-mandatory overflow-x-scrollon the container. This enables the native scrolling and snapping.snap-starton each slide. This makes the slides snap to the start of the container.flex-none basis-fullon each slide. This makes the slides take up the full width of the container.
<div class="flex snap-x snap-mandatory overflow-x-scroll">
<div class="flex-none basis-full snap-start">Slide 1</div>
<div class="flex-none basis-full snap-start">Slide 2</div>
<div class="flex-none basis-full snap-start">Slide 3</div>
</div>Hiding the scrollbar
You can use the following CSS to hide the scrollbar on the snap slider.
@layer components {
.scrollbar-hide {
scrollbar-width: none;
}
.scrollbar-hide::-webkit-scrollbar {
display: none;
}
}Apply it to the snap slider container.
<div class="snap-x snap-mandatory overflow-x-scroll scrollbar-hide">...</div>