# Spiral 3D Slider

> An autoplaying image gallery that flows along a 3D spiral of curved WebGL planes and responds to wheel and page scroll.

A three.js gallery that threads your images along a helix: the front image sits sharp and full size, the rest curve away, shrink and blur with distance. It drifts on its own while idle; scroll the wheel over it (or scroll the page while it is visible) to move along the spiral.

<demo-spiral-3d-slider>



</demo-spiral-3d-slider>

## Installation

```bash
npx shadcn-vue@latest add "https://nxui.geoql.in/r/spiral-3d-slider.json"
```

## Usage

```vue
<script setup lang="ts">
  import Spiral3dSlider from '~/components/ui/spiral-3d-slider/Spiral3dSlider.vue';
  import type { Spiral3dSlide } from '~/components/ui/spiral-3d-slider/types';

  // Local files or remote image URLs both work.
  const slides: Spiral3dSlide[] = [
    { src: '/images/gallery/photo-01.jpg', alt: 'Describe the first image' },
    { src: '/images/gallery/photo-02.jpg', alt: 'Describe the second image' },
    { src: '/images/gallery/photo-03.jpg', alt: 'Describe the third image' },
  ];
</script>

<template>
  <Spiral3dSlider
    :items="slides"
    auto-rotate
    :auto-speed="0.13"
    class="min-h-180"
  />
</template>
```

Fewer than 16 images are repeated to fill the spiral. Remote images must allow
cross-origin loading, because they are uploaded as WebGL textures.

## Props

<table>
<thead>
  <tr>
    <th>
      Prop
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        items
      </code>
    </td>
    
    <td>
      <code>
        Spiral3dSlide[]
      </code>
    </td>
    
    <td>
      required
    </td>
    
    <td>
      Images (<code>
        { src, alt }
      </code>
      
      ) arranged along the spiral
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        radius
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        235
      </code>
    </td>
    
    <td>
      Maximum horizontal radius of the spiral in pixels
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        vertical-gap
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        64
      </code>
    </td>
    
    <td>
      Vertical pitch between neighboring images in pixels
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        card-width
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        255
      </code>
    </td>
    
    <td>
      Maximum width of each image plane in pixels
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        card-aspect-ratio
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        1.5
      </code>
    </td>
    
    <td>
      Width divided by height for every image plane
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        auto-rotate
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Advance the spiral while idle
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        auto-speed
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        0.13
      </code>
    </td>
    
    <td>
      Automatic movement in slides per second
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        scroll-sensitivity
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        0.0024
      </code>
    </td>
    
    <td>
      Spiral movement per pixel of wheel or page scroll
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        smoothing
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        0.065
      </code>
    </td>
    
    <td>
      Interpolation strength (0–1) for the motion
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blur-strength
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        1.65
      </code>
    </td>
    
    <td>
      Maximum blur applied as images move away from focus
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bend
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        0.17
      </code>
    </td>
    
    <td>
      How far each segmented plane curves into the spiral
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fov
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        44
      </code>
    </td>
    
    <td>
      Perspective camera field of view in degrees
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        aria-label
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        'Spiral image gallery'
      </code>
    </td>
    
    <td>
      Accessible name for the gallery region
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        class
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        ''
      </code>
    </td>
    
    <td>
      Additional classes for the stage
    </td>
  </tr>
</tbody>
</table>

## Accessibility

- The stage is a `region` labelled by `aria-label`; every image's `alt` text is listed in a visually hidden list, since the canvas itself is not readable.
- With `prefers-reduced-motion: reduce`, auto-rotation stops and scroll moves the spiral without easing.
- Rendering pauses while the gallery is off screen, and all textures, geometry and the WebGL context are released on unmount.
- If WebGL is unavailable, a short status message replaces the canvas.

## Credits

- Ported from [componentry.fun](https://componentry.dev/docs/components/spiral-3d-slider) by Harsh Jadhav.