React 3D Slideshow

> Warning: This library is a work in progress and has not been thoroughly tested. Use at your own risk in production environments.

A React slideshow component with 3D transitions powered by Three.js and @react-three/fiber.

Live Demo

Installation

``bash
npm install @dylanwells/react-3d-slideshow
`

Quick Start

`tsx
import { Slideshow } from '@dylanwells/react-3d-slideshow'

const slides = [
{ id: 1, image: '/image1.jpg' },
{ id: 2, image: '/image2.jpg' },
{ id: 3, image: '/image3.jpg' },
]

function App() {
return (
slides={slides}
style="glitch"
aspectRatio={16 / 9}
autoPlay
loop
/>
)
}
`

Transition Styles

- glitch - Chromatic aberration, scanlines, and film grain effects
- cascade - 3D cube grid with diagonal wave animation
- cube - Simple 3D cube rotation between slides

Props

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| slides | SlideData[] | required | Array of slide objects with id and image properties |
| style | 'glitch' \| 'cascade' \| 'cube' | 'cascade' | Transition style to use |
| transitionDuration | number | 800 | Duration of transitions in milliseconds |
| aspectRatio | number | 1.5 (3:2) | Aspect ratio for the slideshow display area |
| fullscreen | boolean | false | Fill the entire viewport (glitch and cascade only) |

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| autoPlay | boolean | false | Automatically advance slides |
| autoPlayInterval | number | 5000 | Time between auto-advances in milliseconds |
| pauseOnHover | boolean | true | Pause autoplay when hovering over the slideshow |
| loop | boolean | true | Loop back to first slide after reaching the end |

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| width | string \| number | '100%' | Width of the slideshow container |
| height | string \| number | 400 | Height of the slideshow container |
| initialSlide | number | 0 | Index of the initial slide to display |
| className | string | - | CSS class for the container element |

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| showControls | boolean | true | Show prev/next navigation buttons |
| showIndicators | boolean | true | Show slide indicator dots |
| enableSwipe | boolean | true | Enable touch swipe and mouse drag navigation |
| enableKeyboard | boolean | true | Enable arrow key navigation |

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| loadingSpinner | ReactElement \| null | default spinner | Custom loading spinner. Set to null to hide |
| prevButton | ReactElement \| null | default button | Custom previous button. Set to null to hide |
| nextButton | ReactElement \| null | default button | Custom next button. Set to null to hide |
| renderIndicator | (index: number, isActive: boolean) => ReactElement | - | Custom indicator renderer |
| focusRingStyles | FocusRingStyles | - | Customize keyboard focus ring appearance |

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| glitchAberration | number | 0.5 | Chromatic aberration intensity (0-1) |
| glitchScanlines | number | 0.5 | Scanlines effect intensity (0-1) |
| glitchGrain | number | 0.5 | Film grain effect intensity (0-1) |

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| cascadeMinTiles | number | 10 | Minimum number of tiles in the shorter dimension |

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| ariaLabel | string | 'Image slideshow' | Accessible label for the slideshow region |
| getSlideAriaLabel | (index: number, total: number) => string | - | Custom function to generate slide announcements |
| focusRingStyles | FocusRingStyles | - | Customize focus ring color, width, and offset |

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| fallback | ReactElement \| null | crossfade slideshow | Custom fallback when WebGL is unavailable. Set to null to show nothing |
| onWebGLUnsupported | () => void | - | Callback fired when WebGL is not supported |

$3

| Prop | Type | Description |
|------|------|-------------|
| onSlideChange | (index: number) => void | Called when the active slide changes |
| onWebGLUnsupported | () => void | Called when WebGL is not available |

Customization

$3

`tsx
slides={slides}
prevButton={}
nextButton={}
/>
`

Set to null to hide a button entirely:

`tsx
slides={slides}
prevButton={null} // Hide prev button
nextButton={}
/>
`

$3

`tsx
slides={slides}
renderIndicator={(index, isActive) => (