Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/eyalzh/react-headless-gallery
React headless gallery / carousel component
https://github.com/eyalzh/react-headless-gallery
carousel headless react
Last synced: 3 months ago
JSON representation
React headless gallery / carousel component
- Host: GitHub
- URL: https://github.com/eyalzh/react-headless-gallery
- Owner: eyalzh
- License: mit
- Created: 2023-10-06T11:37:44.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-04-08T17:59:31.000Z (7 months ago)
- Last Synced: 2024-07-12T05:04:51.862Z (4 months ago)
- Topics: carousel, headless, react
- Language: TypeScript
- Homepage:
- Size: 91.8 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-react-headless-components - react-headless-gallery - Fully headless, zero-dependencies gallery / carousel React component. (Libraries)
README
# React Headless Gallery
Headless, zero-dependencies, gallery/carousel component.
## Features
- Infinite sliding (circular gallery)
- Sliding animation (configurable)
- Self looping (configurable)
- Gallery indicators
- Allows for lazy loading of gallery items (see example below)
- Freely style and position all elements of the component
- Built with accessibility in mind (see accessibility below)
## Install
```bash
npm install react-headless-gallery
```
```bash
yarn add react-headless-gallery
```
## Example
[Click here for a live demo](https://headless-demo2.s3.us-east-2.amazonaws.com/index.html)
## Code Example
The following code example uses TailwindCSS to style the gallery, as shown in the image above:
```jsx
function MyGallery() {
const items = [
{
id: 1,
content: (
),
},
{
id: 2,
content: (
),
},
{
id: 3,
content: (
),
},
] as const;
return (
{items.map((item) => (
{item.content}
))}
{[...Array(items.length)].map((_, i) => (
`text-sm cursor-pointer ${isCurrent ? "text-gray-800" : "text-gray-300"}`
}
>
⬤
))}
);
}
```
## Accessibility
The gallery's controls (next, prev, and indicators) are buttons with ARIA labels that can be changed. They are defined as controlling the gallery container with the aria-controls attribute. Please note that all items in the gallery will have the aria-hidden attribute, except for the item that is currently being shown. Items in the gallery should not include focusable elements.
## API
### Gallery
| Name | Type | Description |
|------|------|-------------|
| `transitionDurationMS` | `number` | The duration of the transition in milliseconds. Default: `300`. |
| `transitionTimingFunction` | `EasingFunction` | The timing function for the transition. Default: `ease-in-out`. |
| `selfLooping` | `false \| number` | Enable self-looping. If a number is provided, it will be used as the looping interval in milliseconds. Default: `false` |
| `stopLoopingOnInteraction` | `boolean` | If true, self looping will stop when the gallery is interacted with (default: `true`) |
| `className` | `string` | Additional CSS classes to apply to the component. |
| `style` | `React.CSSProperties` | Inline styles to apply to the component. |
| `ref` | `React.Ref` | ref object to the HTML container element. |
### Gallery.Indicator
| Name | Type | Description |
|------|------|-------------|
| `galleryItemIndex` | `number` | The index of the item to switch to. |
| `aria-label` | ` string \| ((itemNumber: number, isCurrent: boolean) => string)` | ARIA label for the button. |
| `className` | `string \| ((isCurrent: boolean) => string)` | Additional CSS classes to apply to the component. |
| `style` | `React.CSSProperties` | Inline styles to apply to the button. |
| `ref` | `React.Ref` | ref object to the HTML button element. |
## Gallery.Prev and Gallery.Next
| Name | Type | Description |
|------|------|-------------|
| `aria-label` | ` string` | ARIA label for the button. |
| `className` | `string` | Additional CSS classes to apply to the component. |
| `style` | `React.CSSProperties` | Inline styles to apply to the button. |
| `ref` | `React.Ref` | ref object to the HTML button element. |
## Note on infinite sliding
To implement infinite sliding, the first and last gallery elements are cloned - each will appear twice in the DOM. If that causes undesirable side effects, please create an issue.