# @slidy/react
Simple, configurable & reusable carousel component built with React based on [@slidy/core](https://github.com/Valexr/slidy/tree/master/packages/core).
Try the [demo](https://codesandbox.io/s/slidy-react-demo-64wllu?file=/src/App.tsx).
## Getting started
The package is available via [npm](https://www.npmjs.com/package/@slidy/react):
```
npm i @slidy/react
```
## Usage
The most simple way to get started is to use named import of `` component:
```jsx
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 ;
};
```
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:**
```jsx
import '@slidy/react/dist/slidy.css';
```
## Core Component
`Core` is a wrapper component for [@slidy/core](https://github.com/Valexr/slidy/tree/master/packages/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.
```tsx
import { Core } from '@slidy/react';
export default () => {
return ;
};
```
### 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>` | Set's index of a current slide. |
| `plugins` | `undefined` | `ReturnType[]` | 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) => 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) => void` | Listen to the core event `keys` to fire. |
| `onUpdate` | `undefined` | `(event: CustomEvent) => void` | Listen to the core event `update` to fire. |
| `onDestroy` | `undefined` | `(event: CustomEvent) => void` | Listen to the core event `destroy` to fire. |
For TypeScript users there is the `SlidyCoreOptions` interface available via named import.
## Slidy Component
`` component uses `` internally and provides more features expected from carousel.
### Slidy Component API
The `` component interface extends the ``. 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 `` 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) => 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) => void` | Listen to the core event `keys` to fire. |
| `onUpdate` | `undefined` | `(event: CustomEvent) => void` | Listen to the core event `update` to fire. |
| `onDestroy` | `undefined` | `(event: CustomEvent) => void` | Listen to the core event `destroy` to fire. |
| `plugins` | `undefined` | `ReturnType[]` | 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:
```jsx
import { Slidy, classNames } from '@slidy/react';
import '@slidy/react/dist/slidy.css';
export default () => {
return (
);
};
```
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 | `` | The arrow control background color. |
| `--slidy-arrow-bg-hover` | #4e4e4e54 | `` | The arrow control hover background color. |
| `--slidy-arrow-icon-color` | currentColor | `` | The arrow control icon fill color. |
| `--slidy-arrow-size` | 24px | `` | The arrow controls size. |
| `--slidy-autoplay-control-size` | 2.25em | `` | The autoplay control size. |
| `--slidy-autoplay-indicator-accent` | lightpink | | The autoplay control indicator ring color. |
| `--slidy-counter-bg` | #4e4e4ebf | `` | The counter's background color. |
| `--slidy-focus-ring-color` | #c9c9c9e6 | `` | Focus ring color for all focusable elements. |
| `--slidy-height` | 100% | `` | The height of the component's node. |
| `--slidy-nav-item-color` | white | `` | The navigation elements color. |
| `--slidy-nav-item-radius` | 50% | `` | The navigation elements border radius. |
| `--slidy-nav-item-size` | 16px | `` | The navigation elements size. |
| `--slidy-progress-thumb-color` | #c44f61 | `` | The progress bar active track color. |
| `--slidy-progress-track-color` | #96969680 | `` | The progress bar track color. |
| `--slidy-progress-track-size` | 5px | `` | The progress bar height. |
| `--slidy-slide-aspect-ratio` | unset | `` | Defines the slide aspect-ratio. |
| `--slidy-slide-bg-color` | darkgray | `` | The placeholder background color for loading images. |
| `--slidy-slide-gap` | 1rem | `` | The gap between items in carousel. |
| `--slidy-slide-height` | 100% | `` | The carousel items height. |
| `--slidy-slide-object-fit` | cover | - | The carousel items (images) resize behaviour. |
| `--slidy-slide-radius` | 1rem | `` | The slide's border radius value. |
| `--slidy-slide-width` | auto | `` | The carousel items width. |
| `--slidy-thumbnail-radius` | 0.5rem | `` | The thumbnail `border-radius` value. |
| `--slidy-thumbnail-size` | 50px | `` | The thumbnail panel size. |
| `--slidy-width` | 100% | `` | 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:
```css
.parent {
--slidy-navigation-color: red;
}
```
```jsx
export default () => {
return (
);
};
```
Or just pass a class with a set of custom properties:
```css
.some-class {
--slidy-navigation-color: red;
--slidy-nav-item-size: 1rem;
}
```
```jsx
import { Slidy, classNames } from '@slidy/react';
import '@slidy/react/dist/slidy.css';
export default () => {
return (
);
};
```
## Slots
### `arrow`
Customizes the content of the default arrow controls.
### `arrows`
Provides a slot for custom arrow buttons.
If the nodes are ` ` 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.
```css
button:first-of-type {
grid-area: prev-slide;
}
button:last-of-type {
grid-area: next-slide;
}
```
```jsx
export default () => {
return (
(
<>
)}
/>
);
};
```
### `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.
```jsx
export default () => {
return (
{(item) => (
{item.figcaption}
)}
);
};
```
### `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.
```jsx
export default () => {
return } />;
};
```
## 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.
```jsx
import { Slidy } from '@slidy/react';
import { useState } from 'react';
import '@slidy/react/dist/slidy.css';
export default () => {
const [index, setIndex] = useState(0);
return (
<>
);
};
```
## 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
---
_Source: https://npm.io/package/@slidy/react · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
