# Carousel
> Carousel of four procedural pixel scenes with an ordered-dither dissolve between slides; autoplay pauses on hover or focus.
- Element: `<hf-carousel>`
- React: `import { HfCarousel } from "@/components/lumesec/hf-carousel"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-carousel.json
- Page: https://elements.lumesec.ai/components/pixel-hd/carousel



Live preview: https://elements.lumesec.ai/view/hf-carousel

```html
<hf-carousel autoplay></hf-carousel>
```

## Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

## Installation

```bash
npx shadcn@latest add @lumesec/hf-carousel
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/hf-carousel.json
```

## Usage

React:

```tsx
import { HfCarousel } from "@/components/lumesec/hf-carousel";

export function Example() {
  return (
    <HfCarousel autoplay />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/hf-carousel.js"></script>

<hf-carousel autoplay></hf-carousel>
```

## Behaviour

Four procedural scenes. Slides change with an ordered-dither dissolve and a bright front, autoplay pauses on hover or focus, and it swipes.

## API reference

### Attributes

| Attribute  | React prop | Type      | Default | Description                                                                                                                                                                                     |
| ---------- | ---------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autoplay` | `autoplay` | `boolean` | `false` | Presence attribute. Advances every 5 s and draws a progress line along the bottom. Pauses while hovered, focused or off-screen. Checked every frame, so it can be added or removed at any time. |

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event    | React prop | Detail              | Description                                                                      |
| -------- | ---------- | ------------------- | -------------------------------------------------------------------------------- |
| `change` | `onChange` | `{ index: number }` | Fires when the slide changes, by user action or autoplay. `index` is zero-based. |

### Methods

Call them on the element, for example through a React ref.

| Method              | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| `go(index: number)` | Shows the slide at `index`; values outside 0–3 wrap around. |

## Keyboard

| Keys                   | Action                            |
| ---------------------- | --------------------------------- |
| ArrowLeft / ArrowRight | Previous or next slide, wrapping. |

## Accessibility

* The slide area is a focusable `role="region"` with `aria-roledescription="carousel"` and `aria-label="Pixel scenes"`.
* The canvas has `role="img"` and an `aria-label` such as `Slide 1 of 4: Aurora over the ridge`.
* The caption is an `aria-live="polite"` region, including during autoplay.
* Previous and Next buttons have `aria-label`s; dot buttons are labelled `Slide <n>: <title>`, and the current one has `aria-current="true"`.
* There is no pause button; autoplay pauses only on hover or focus.
* Reduced motion: autoplay does not advance, slides switch without the dissolve and the scenes are static.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--lumesec` and `--muted`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent` and `--ui-track`.

## Notes

* The four scenes are generated in code and cannot be replaced.
* A horizontal swipe of more than 40px changes the slide. The image is 210px tall and fills the width.