Carousel

Installation

Copy editable source into an initialized application:

pnpm dlx @simurgh-ui/cli add carousel

For package consumption, import from the component subpath and load its optional recipe CSS:

React

import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselPrevious,
  CarouselNext,
} from '@simurgh-ui/react/carousel';
import '@simurgh-ui/styles/carousel.css';

Vue

import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselPrevious,
  CarouselNext,
} from '@simurgh-ui/vue/carousel';
import '@simurgh-ui/styles/carousel.css';

Angular

import {
  CarouselComponent,
  CarouselContentComponent,
  CarouselItemComponent,
  CarouselPreviousComponent,
  CarouselNextComponent,
} from '@simurgh-ui/angular/carousel';
import '@simurgh-ui/styles/carousel.css';

Omit the component stylesheet for fully headless styling. CLI-copied components use the local path written to simurgh.json and the copied application styles instead of these package imports.

Purpose

Carousel exposes a named region, one visible slide at a time, positional slide labels, bounded controls, and logical Arrow Left/Right navigation. Enable loop only when wrapping is expected.

Default presentation: styled

The optional component stylesheet provides a complete default recipe, including visual hierarchy and interaction states. Consumers can override semantic tokens or omit the recipe.

Basic usage

Live component Carousel

Design system

Shared accessible patterns for product teams.

Anatomy

The public component parts are listed in API surface below. Use only the parts needed by the example; compound components depend on their documented parent/child nesting.

State model

Controlled state remains the application’s source of truth and must be updated from every change event. Uncontrolled state reads its default only when the component mounts. Do not pass both forms of the same state at once.

Framework	Exact state contract and reset behavior
React	No public controlled/uncontrolled state pair is exposed.
Vue	Controlled: `v-model:index` (`index` + `update:index`). Uncontrolled: `defaultIndex`. Reset the model ref to its initial value; reset uncontrolled state with a changed Vue `:key`.
Angular	No public two-way state binding is exposed.

Vue

<script setup lang="ts">
import { ref } from 'vue';
const initial = '';
const state = ref(initial);
const resetKey = ref(0);
</script>

<Carousel v-model:index="state">…</Carousel>
<button @click="state = initial">Reset controlled</button>
<Carousel :key="resetKey" :defaultIndex="initial">…</Carousel>
<button @click="resetKey++">Reset uncontrolled</button>

The carousel itself is focusable in Angular; in React and Vue, arrow events from focused controls bubble to the root. Supply concise slide content and avoid automatic advancement unless users can pause it.

Examples

<Carousel label="Featured projects">
  <CarouselContent>
    <CarouselItem>Design system</CarouselItem>
    <CarouselItem>Documentation</CarouselItem>
  </CarouselContent>
  <CarouselPrevious>‹</CarouselPrevious>
  <CarouselNext>›</CarouselNext>
</Carousel>

<Carousel label="Featured projects">
  <CarouselContent>
    <CarouselItem>Design system</CarouselItem>
    <CarouselItem>Documentation</CarouselItem>
  </CarouselContent>
  <CarouselPrevious>‹</CarouselPrevious>
  <CarouselNext>›</CarouselNext>
</Carousel>

<simurgh-carousel label="Featured projects">
  <simurgh-carousel-content>
    <simurgh-carousel-item>Design system</simurgh-carousel-item>
    <simurgh-carousel-item>Documentation</simurgh-carousel-item>
  </simurgh-carousel-content>
  <simurgh-carousel-previous>‹</simurgh-carousel-previous>
  <simurgh-carousel-next>›</simurgh-carousel-next>
</simurgh-carousel>

Keyboard interactions

These keys describe behavior implemented by the adapters. Native Tab, Enter, and Space behavior still applies to descendant links, buttons, and form controls unless the component overrides it.

Concern / keys	Behavior
Focus entry and exit (Tab / Shift+Tab)	Tab reaches the viewport and controls in DOM order.
Navigation and activation	Arrow Left/Right moves to the previous/next item.
Escape	Not handled by the component.
RTL differences	Previous/next Arrow Left/Right mapping reverses in RTL.
Typeahead	Not supported.

Accessibility

Preserve the documented composition and accessible names when wrapping or restyling this component. See accessibility and RTL guidance for keyboard, focus, labeling, and directionality requirements.

API surface

React exports: Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext
Vue exports: Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext
Angular exports: CarouselComponent, CarouselContentComponent, CarouselItemComponent, CarouselPreviousComponent, CarouselNextComponent

Import these public symbols from the component subpath shown in Installation. Framework-specific props, events, slots, directives, methods, defaults, and native-attribute behavior belong in the API tables on this page; use the linked source only to verify the current implementation.

React API reference

React

An inherited-attributes entry means the component accepts the complete named React native interface, including its event handlers and ARIA and data attributes. Remaining attributes are forwarded to the rendered element unless the component behavior described on this page overrides them.

`Carousel`

Inherited attributes: HTMLAttributes<HTMLDivElement>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`
`defaultIndex`	`number`	`undefined`
`direction`	`Direction`	`undefined`
`label`	`string`	`undefined`
`loop`	`boolean`	`undefined`
`onIndexChange`	`(index: number) => void`	`undefined`

`CarouselContent`

Inherited attributes: HTMLAttributes<HTMLDivElement>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`

`CarouselItem`

Inherited attributes: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`
`ref`	`Ref<HTMLDivElement> \| undefined`	`undefined`

`CarouselPrevious`

Inherited attributes: ButtonHTMLAttributes<HTMLButtonElement>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`

`CarouselNext`

Inherited attributes: ButtonHTMLAttributes<HTMLButtonElement>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`

Vue API reference

Vue

Boolean props without explicit defaults use Vue’s false default. Undeclared attributes follow the fallthrough behavior stated for each component.

`Carousel`

Vue attribute fallthrough is enabled for the rendered root.

Prop	Type	Default / requirement
`label`	`string`	`'Carousel'`
`direction`	`Direction`	`'ltr'`
`loop`	`boolean`	`false`
`defaultIndex`	`number`	`0`

Event	Payload
`update:index`	`number`

Slots: default.

Exposed methods: none.

`CarouselContent`

Vue attribute fallthrough is enabled for the rendered root.

No declared props.

No emitted events.

Slots: default.

Exposed methods: none.

`CarouselItem`

Vue attribute fallthrough is enabled for the rendered root.

No declared props.

No emitted events.

Slots: default.

Exposed methods: none.

`CarouselPrevious`

Vue attribute fallthrough is enabled for the rendered root.

No declared props.

No emitted events.

Slots: default.

Exposed methods: none.

`CarouselNext`

Vue attribute fallthrough is enabled for the rendered root.

No declared props.

No emitted events.

Slots: default.

Exposed methods: none.

Angular API reference

Angular

Inputs and outputs use their public template names. Public methods are callable through a template reference or ViewChild. Native attributes apply to the documented template root or directive host; they are not automatically forwarded through component hosts.

`CarouselComponent`

Component selector: simurgh-carousel. The template’s first native element is ng-content. Angular host bindings: { 'data-slot': 'carousel', role: 'region', 'aria-roledescription': 'carousel', '[attr.aria-label]': 'label', '[attr.dir]': 'direction', tabindex: '0', }.

Input	Type	Default / requirement
`label`	`string`	`'Carousel'`
`direction`	`Direction`	`'ltr'`
`loop`	`boolean`	`false`
`defaultIndex`	`number`	`undefined`

Output	Payload
`indexChange`	`number`