@slidy/react

Simple, configurable & reusable carousel component built with React based on @slidy/core.

Try the demo.

Getting started

The package is available via npm:

npm i @slidy/react

Usage

The most simple way to get started is to use named import of <Slidy /> component:

import { Slidy } from '@slidy/react';
import '@slidy/react/dist/slidy.css';

const slides = [
    {
        id: 1,
        width: 800,
        height: 1200,
        src: 'static/img/some-image.webp',
    },
];

export default () => {
    return <Slidy slides={slides} />;
};

All props are optional. The only property to get started is slides - an array of objects with image related data.

You will also have to import css styles:

import '@slidy/react/dist/slidy.css';

Core Component

Core is a wrapper component for @slidy/core available via named import. It is best to use to build up the custom component for specific needs or when just the basic functionality is needed.

import { Core } from '@slidy/react';

export default () => {
    return <Core />;
};

Core Component API

| Property | Default | Type | Description | | :---------- | :---------: | :-----------------------------------------------------------------: | :-------------------------------------------------------------------- | | animation | undefined | AnimationFunc | Custom slide animation. | | axis | "x" | "x" or "y" | The scroll direction. | | clamp | 0 | number | Clamps sliding index as {clamp} - {index} + {clamp} | | className | "" | string | Passes the class to the node. | | duration | 450 | number | Slide transitions duration value. | | easing | undefined | (t: number => number) | Inertion scroll easing behaviour. | | gravity | 1.2 | number | Scroll inertia value. | | indent | 0 | number | Custom scroll indent value, calculates as gap * indent. | | index | 0 | number | The index of the initial slide. | | setIndex | undefined | React.Dispatch<React.SetStateAction<number>> | Set's index of a current slide. | | plugins | undefined | ReturnType<PluginFunc>[] | Plugins to operate with the slidy instance and its options directly. | | loop | false | boolean | Makes the slideshow continious. | | sensity | 5 | number | Defines the sliding sensity as the number of pixels required to drag. | | snap | undefined | "start" or "center" or "end" or "deck" | Enforces the scroll stop positions. | | tag | ol | string | The HTML tag name to render. | | onResize | undefined | (event: CustomEvent<{ ROE: ResizeObserverEntry[] }>) => void | Listen to the core event resize to fire. | | onMount | undefined | (event: CustomEvent<Options>) => void | Listen to the core event mount to fire. | | onMove | undefined | (event: CustomEvent<{ index: number; position: number }>) => void | Listen to the core event move to fire. | | onIndex | undefined | (event: CustomEvent<{ index: number }>) => void | Listen to the core event index to fire. | | onKeys | undefined | (event: CustomEvent<string>) => void | Listen to the core event keys to fire. | | onUpdate | undefined | (event: CustomEvent<Options>) => void | Listen to the core event update to fire. | | onDestroy | undefined | (event: CustomEvent<HTMLElement>) => void | Listen to the core event destroy to fire. |

For TypeScript users there is the SlidyCoreOptions interface available via named import.

Slidy Component

<Slidy /> component uses <Core /> internally and provides more features expected from carousel.

Slidy Component API

The <Slidy /> component interface extends the <Core />. There are a list of additional options available:

| Property | Default | Type | Description | | :------------ | :----------------: | :-----------------------------------------------------------------: | :----------------------------------------------------------------------- | | arrows | true | boolean or () => JSXElement | Renders the arrow button controls for accessible slide navigation. | | arrow | undefined | () => JSXElement | Renders the arrow. | | children | undefined | (item: Slide) => JSXElement | Renders each slide. | | overlay | undefined | () => JSXElement | Renders the overlay. | | background | false | boolean | Sets background-image instead of <img /> elements to display slides. | | classNames | SlidyStyles | SlidyStylesDefault | The class names object used over the component. | | getImgSrc | item => item.src | function | The slide's src attribute getter. | | getThumbSrc | item => item.src | function | The thumbnail's src attribute getter. | | i18n | i18nDefaults | I18NDict | The i18n localization dictionary. | | navigation | false | boolean | Renders the navigation controls for pagination-like slide navigation. | | groups | 0 | number | Controls the number of items displayed per viewport. | | progress | false | boolean | Renders the progress bar. | | slides | [] | Slides[] | An array of objects with image metadata. | | thumbnail | false | boolean or () => JSXElement | Renders the thumbnail navigation panel. | | onResize | undefined | (event: CustomEvent<{ ROE: ResizeObserverEntry[] }>) => void | Listen to the core event resize to fire. | | onMount | undefined | (event: CustomEvent<Options>) => void | Listen to the core event mount to fire. | | onMove | undefined | (event: CustomEvent<{ index: number; position: number }>) => void | Listen to the core event move to fire. | | onIndex | undefined | (event: CustomEvent<{ index: number }>) => void | Listen to the core event index to fire. | | onKeys | undefined | (event: CustomEvent<string>) => void | Listen to the core event keys to fire. | | onUpdate | undefined | (event: CustomEvent<Options>) => void | Listen to the core event update to fire. | | onDestroy | undefined | (event: CustomEvent<HTMLElement>) => void | Listen to the core event destroy to fire. | | plugins | undefined | ReturnType<PluginFunc>[] | Plugins to operate with the slidy instance and its options directly. |

By default component works with images. Image object should contain width and height attributes to prevent layout shifts and alt for accessibility.

Styling

Extending/Overriding classes

To extend default component styles use classNames property. Default classes are available via object, that can be extended or overridden:

import { Slidy, classNames } from '@slidy/react';
import '@slidy/react/dist/slidy.css';

export default () => {
    return (
        <Slidy
            classNames={{
                root: `${classNames.root} custom-class`,
                ...classNames,
            }}
        />
    );
};

The classNames consist of { target: className } pairs:

| Target | Default class | Description | | :-------- | :----------------: | :---------------------- | | arrow | slidy-arrow | Arrow controls. | | autoplay | slidy-autoplay | Autoplay control. | | counter | slidy-counter | Slide progress counter. | | img | slidy-img | Slide image node. | | nav | slidy-nav | Slide navigation panel. | | nav-item | slidy-nav-item | Navigtion panel item. | | overlay | slidy-overlay | Slides overlay node. | | progress | slidy-progress | Slide progress bar. | | root | slidy | Component's root node. | | slide | slidy-slide | Slide item node. | | slides | slidy-slides | Slides list node. | | thumbnail | slidy-thumbnail | Thumbnail item. | | thumbnail | slidy-thumbnails | Thumbnails bar. |

Custom Properties API

For easier style customization Slidy provides a set of predefined custom properties to inherit:

List of available public custom properties:

| Property | Default | Type | Description | | :---------------------------------- | :----------: | :---------: | :--------------------------------------------------- | | --slidy-arrow-bg | #4e4e4ebf | <color> | The arrow control background color. | | --slidy-arrow-bg-hover | #4e4e4e54 | <color> | The arrow control hover background color. | | --slidy-arrow-icon-color | currentColor | <color> | The arrow control icon fill color. | | --slidy-arrow-size | 24px | <length> | The arrow controls size. | | --slidy-autoplay-control-size | 2.25em | <length> | The autoplay control size. | | --slidy-autoplay-indicator-accent | lightpink | | The autoplay control indicator ring color. | | --slidy-counter-bg | #4e4e4ebf | <color> | The counter's background color. | | --slidy-focus-ring-color | #c9c9c9e6 | <color> | Focus ring color for all focusable elements. | | --slidy-height | 100% | <length> | The height of the component's node. | | --slidy-nav-item-color | white | <color> | The navigation elements color. | | --slidy-nav-item-radius | 50% | <length> | The navigation elements border radius. | | --slidy-nav-item-size | 16px | <length> | The navigation elements size. | | --slidy-progress-thumb-color | #c44f61 | <color> | The progress bar active track color. | | --slidy-progress-track-color | #96969680 | <color> | The progress bar track color. | | --slidy-progress-track-size | 5px | <length> | The progress bar height. | | --slidy-slide-aspect-ratio | unset | <int/int> | Defines the slide aspect-ratio. | | --slidy-slide-bg-color | darkgray | <color> | The placeholder background color for loading images. | | --slidy-slide-gap | 1rem | <length> | The gap between items in carousel. | | --slidy-slide-height | 100% | <length> | The carousel items height. | | --slidy-slide-object-fit | cover | - | The carousel items (images) resize behaviour. | | --slidy-slide-radius | 1rem | <length> | The slide's border radius value. | | --slidy-slide-width | auto | <length> | The carousel items width. | | --slidy-thumbnail-radius | 0.5rem | <length> | The thumbnail border-radius value. | | --slidy-thumbnail-size | 50px | <length> | The thumbnail panel size. | | --slidy-width | 100% | <length> | The width of the component's node. |

Inherited custom properties

All supported custom properties starts with --slidy-. For example, to recolor navigation controls, let the component inherit a --slidy-nav-item-color custom property from any parent:

.parent {
    --slidy-navigation-color: red;
}

export default () => {
    return (
        <div class="parent">
            <Slidy />
        </div>
    );
};

Or just pass a class with a set of custom properties:

.some-class {
    --slidy-navigation-color: red;
    --slidy-nav-item-size: 1rem;
}

import { Slidy, classNames } from '@slidy/react';
import '@slidy/react/dist/slidy.css';

export default () => {
    return (
        <Slidy
            classNames={{
                root: `${classNames.root} .some-class`,
                ...classNames,
            }}
        />
    );
};

Slots

arrow

Customizes the content of the default arrow controls.

arrows

Provides a slot for custom arrow buttons.

If the nodes are <button /> and the data-step attribute is present, the event listener is not needed. Just provide the values -1 and 1 for data-step on custom buttons.

Also, there are grid-area is present in the layout for this custom controls: prev-slide and next-slide respectively.

button:first-of-type {
    grid-area: prev-slide;
}

button:last-of-type {
    grid-area: next-slide;
}

export default () => {
    return (
        <Slidy
            arrows={() => (
                <>
                    <button data-step="-1"> Show the previous slide </button>
                    <button data-step="1"> Show the next slide </button>
                </>
            )}
        />
    );
};

default

Usually the default markup is not enough. The default slot solves this problem. To use custom slide markup slot expose each slides prop item item argument.

export default () => {
    return (
        <Slidy>
            {(item) => (
                <figure>
                    <img src={item.src} alt={item.figcaption} />
                    <figcaption>{item.figcaption}</figcaption>
                </figure>
            )}
        </Slidy>
    );
};

overlay

Slot to display content overlaid content. It covers the slides area and can be customized by overriding the .slidy-overlay. For example, it is used to display the counter.

export default () => {
    return <Slidy overlay={() => <button> Share </button>} />;
};

i18n

To modify all texts used in the component use pass the dictionary as i18n prop. For the sake of accessibility, it is recommended translating defaults:

| Key | Default | Event detail | | :--------- | :------------------------------ | :------------------------------------------------------------: | | carousel | "carousel" | aria-label of a root element. | | counter | "%s of %s" | aria-label of each slide as {slide number} of {slide length} | | first | "Go to the first slide" | aria-label of the first item at the navigation. | | last | "Go to the last slide" | aria-label of the last item at the navigation. | | next | "Go to the next slide" | aria-label of the arrow control. | | play | "Start autoplay" | aria-label of the autoplay control. | | prev | "Return back to previous slide" | aria-label of the arrow control. | | slide | "Slide" | aria-roledescription of each slide item. | | slideN | "Go to the slide %s" | aria-label of pagination of each slide item. | | stop | "Stop autoplay" | aria-label of the autoplay control. |

Recipes

External controls

It is possible to control the navigation of the Slidy instance from the parent component via binding.

There are two variables available to control the component externally: index and position. Declare the variables to hold the values and bind them to the instance for the carousel control.

import { Slidy } from '@slidy/react';
import { useState } from 'react';

import '@slidy/react/dist/slidy.css';

export default () => {
    const [index, setIndex] = useState(0);

    return (
        <>
            <Slidy slides={slides} index={index} setIndex={setIndex} />
            <button onClick={() => setIndex((prev) => prev + 1)}>Next slide</button>
        </>
    );
};

Possible issues

• Slides should not have absolute positioning, otherwise the core script won't get correct dimentions;
• Using the background option usually is not recommended. In case you need to use it, specify the slide sizes with custom properties: width and height, or just aspect-ratio.

License

Slidy is distributed under the MIT license