Carousel

A scrollable slide container with navigation arrows, dot indicators, auto-play, looping, and keyboard controls.

Components

Carousel

content

interactive

<arc-carousel>

Overview

Carousel presents a sequence of slotted elements as full-width slides within a scroll-snapping viewport. Users navigate between slides using circular arrow buttons on the left and right edges, clickable dot indicators below the viewport, or left/right arrow keys. Each slotted child becomes a slide that snaps into position with smooth scroll behavior, and the component tracks the current index to keep the arrows and dots synchronized. Auto-play mode advances slides on a configurable interval (default 5 seconds) and automatically pauses when the user hovers over the carousel or when any element inside receives keyboard focus, preventing content from changing while the user is interacting. The auto-play timer also respects `prefers-reduced-motion` — if the user has requested reduced motion, auto-play is disabled entirely and scroll behavior falls back to instant jumps. When `loop` is enabled (the default), navigating past the last slide wraps to the first and vice versa, creating an infinite cycle. The arrow buttons are disabled at the edges when looping is off. Dot indicators use a `tablist` ARIA role with individual `tab` roles and `aria-selected` state, allowing screen reader users to jump directly to any slide. The component fires `arc-change` with the new slide index whenever the active slide changes.

Guidelines

When to use

Use Carousel for image galleries, testimonial rotators, or feature highlights
Provide meaningful content in each slide — avoid empty or placeholder slides
Set `auto-play` only when the content is supplementary and not time-sensitive
Include at least 2 slides — a single slide makes the navigation controls meaningless
Use the `arc-change` event to synchronize external indicators or captions with the current slide

When not to use

Do not use Carousel for critical content that users must see — some users never advance past the first slide
Do not set `interval` below 3000ms — slides change too fast to read or interact with
Do not place form inputs inside carousel slides — the scrolling behavior conflicts with input focus
Do not hide navigation arrows and dots simultaneously — the user needs at least one way to navigate
Avoid nesting a Carousel inside another Carousel — the scroll-snapping conflicts are unpredictable

Features

Scroll-snap viewport with smooth scrolling and full-width slides from slotted children
Circular navigation arrows positioned at 50% height on the left and right edges
Dot indicators with `tablist` ARIA role for direct slide navigation
Auto-play mode with configurable interval, pausing on hover and focus
Loop mode wraps navigation at the edges; non-loop mode disables arrows at boundaries
Full keyboard navigation: left/right arrow keys move between slides
Respects `prefers-reduced-motion` by disabling auto-play and using instant scroll
Fires `arc-change` with `{ index }` in the event detail on every slide change

Preview

Slide 1

Slide 2

Slide 3

Usage

This component requires JavaScript. No pure HTML/CSS version is available — use the Web Component directly or a framework wrapper.

<arc-carousel show-arrows show-dots loop>
  <img src="/slide-1.jpg" alt="Slide 1" />
  <img src="/slide-2.jpg" alt="Slide 2" />
  <img src="/slide-3.jpg" alt="Slide 3" />
</arc-carousel>

import { Carousel } from '@arclux/arc-ui-react';

export default function Example() {
  return (
    <Carousel showArrows showDots loop>
      <img src="/slide-1.jpg" alt="Slide 1" />
      <img src="/slide-2.jpg" alt="Slide 2" />
      <img src="/slide-3.jpg" alt="Slide 3" />
    </Carousel>
  );
}

<script setup>
import { Carousel } from '@arclux/arc-ui-vue';
</script>

<template>
  <Carousel show-arrows show-dots loop>
    <img src="/slide-1.jpg" alt="Slide 1" />
    <img src="/slide-2.jpg" alt="Slide 2" />
    <img src="/slide-3.jpg" alt="Slide 3" />
  </Carousel>
</template>

<script>
  import { Carousel } from '@arclux/arc-ui-svelte';
</script>

<Carousel showArrows showDots loop>
  <img src="/slide-1.jpg" alt="Slide 1" />
  <img src="/slide-2.jpg" alt="Slide 2" />
  <img src="/slide-3.jpg" alt="Slide 3" />
</Carousel>

import { Component } from '@angular/core';
import { Carousel } from '@arclux/arc-ui-angular';

@Component({
  imports: [Carousel],
  template: `
    <arc-carousel [showArrows]="true" [showDots]="true" [loop]="true">
      <img src="/slide-1.jpg" alt="Slide 1" />
      <img src="/slide-2.jpg" alt="Slide 2" />
      <img src="/slide-3.jpg" alt="Slide 3" />
    </arc-carousel>
  `,
})
export class MyComponent {}

import { Carousel } from '@arclux/arc-ui-solid';

export default function Example() {
  return (
    <Carousel showArrows showDots loop>
      <img src="/slide-1.jpg" alt="Slide 1" />
      <img src="/slide-2.jpg" alt="Slide 2" />
      <img src="/slide-3.jpg" alt="Slide 3" />
    </Carousel>
  );
}

import { Carousel } from '@arclux/arc-ui-preact';

export default function Example() {
  return (
    <Carousel showArrows showDots loop>
      <img src="/slide-1.jpg" alt="Slide 1" />
      <img src="/slide-2.jpg" alt="Slide 2" />
      <img src="/slide-3.jpg" alt="Slide 3" />
    </Carousel>
  );
}

API

auto-play boolean =false: Enables automatic slide advancement on a timer. Pauses on hover and focus, respects prefers-reduced-motion.
interval number =5000: Auto-play interval in milliseconds between slide transitions.
loop boolean =true: Enables wrapping at the edges so the last slide connects to the first and vice versa.
show-dots boolean =true: Shows dot indicators below the viewport for direct slide navigation.
show-arrows boolean =true: Shows previous/next arrow buttons on the left and right edges of the viewport.

Events

arc-change: Fired when the active slide changes

Carousel

Overview

Guidelines

When to use

When not to use

Features

Preview

Usage

API

Events

See Also

Docs

Project

Arclight