React slider

Also known as: Swooper

This package contains a basic modern slider (±2.5kb gzipped). The purpose of this slider is to provide a simple React component which can be controlled in a userfriendly way on mobile, tablet and desktop.

The aim is to keep the slider as basic as possible, while exposing an API that allows more advanced implementations to be realised.

Demo page: https://yoursurprisecom.github.io/slider/

This slider has the following features:

• Free scroll on mobile with native CSS scroll snapping
• Drag to scroll on devices with a mouse
• Buttons to navigate on devices with a mouse
• Support for multiple variable width slides

Todos (help appreciated):

• Expand end-to-end test suite
• Improve accessibility
• Reduce amount of required tooling

All browsers with support for IntersectionObserver and scroll-snap are supported.

Installation

npm

npm install @yoursurprise/slider --save

yarn

yarn add @yoursurprise/slider

Import the CSS files

import "@yoursurprise/slider/dist/index.css";

Implement the Slider

import {Slider} from '@yoursurprise/slider';
import '@yoursurprise/slider/dist/index.css';

export default function YourComponent() {
    return (
        <Slider>
            <div>1</div>
            <div>2</div>
            <div>3</div>
            <div>4</div>
        </Slider>
    );
}

Configuration

Option	Type	Required	Default	Description
hideNavigationButtons	boolean	false	false	Always hides the navigation buttons
initialSlideIndex	number	false	0	Open the Slider at a specific index
onSlide	function	false	undefined	A callback function that is called when the user slides
direction	string	false	horizontal	Direction of the slider: 'horizontal' or 'vertical'

API

API method	Type	Returns	Description
getFirstFullyVisibleSlideIndex	function	number	Retrieve the first fully visible slide index
getLastFullyVisibleSlideIndex	function	number	Retrieve the last fully visible slide index
scrollToSlide	function	void	Scroll the slider to a specific slide
scrollToNextSlide	function	void	Scroll the slider to the next slide
scrollToPreviousSlide	function	void	Scroll the slider to the previous slide

Example on how to access the slider API:

export default function YourComponent() {
    const sliderApi = useRef();

    useEffect(() => {
        if (sliderApi.current) {
            sliderApi.current.getFirstFullyVisibleSlideIndex();
        }
    }, [sliderApi.current]);

    return (
        <Slider ref={sliderApi}>
            <div>1</div>
            <div>2</div>
            <div>3</div>
            <div>4</div>
        </Slider>
    );
}

Development

End-to-end tests

Prior to developing or running end-to-end tests, install the browsers in which the tests will run:

npx playwright install

Afterwards, the tests can be run using:

npm run e2e-tests

Or alternatively the test interface can be opened using:

npm run e2e-tests-ui