@slidy/react v1.2.0

@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

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:

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:

Custom Properties API

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

List of available public custom properties:

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:

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