Primitives

Carousel

A slideshow of content panels with previous / next controls, an indicator group, optional looping and multi-slide views, and an accessible autoplay mode with a pause control.

forty-cdk/carousel WAI-ARIA APG

Page through the slides with the buttons, the arrow keys or a drag. The root carries data-orientation, and data-dragging is on while a pointer holds the track.

Source

The coast road north

Four days, three ferries and one small car.

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  ForCarousel,
  ForCarouselIndicator,
  ForCarouselIndicators,
  ForCarouselNext,
  ForCarouselPrevious,
  ForCarouselSlide,
  ForCarouselTrack,
  ForCarouselViewport,
} from 'forty-cdk/carousel';

interface Slide {
  readonly id: number;
  readonly title: string;
  readonly summary: string;
}

@Component({
  selector: 'app-carousel-default-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    ForCarousel,
    ForCarouselViewport,
    ForCarouselTrack,
    ForCarouselSlide,
    ForCarouselPrevious,
    ForCarouselNext,
    ForCarouselIndicators,
    ForCarouselIndicator,
  ],
  template: `
    <div
      forCarousel
      class="car"
      [(activeIndex)]="activeIndex"
      loop
      orientation="horizontal"
      align="start"
      ariaLabel="Featured stories"
    >
      <div class="car-controls-row">
        <button forCarouselPrevious class="car-btn" aria-label="Previous slide">
          <svg viewBox="0 0 24 24" aria-hidden="true">
            <path
              d="m15.75 19.5-7.5-7.5 7.5-7.5"
              fill="none"
              stroke="currentColor"
              stroke-width="1.75"
              stroke-linecap="round"
              stroke-linejoin="round"
            />
          </svg>
        </button>
        <button forCarouselNext class="car-btn" aria-label="Next slide">
          <svg viewBox="0 0 24 24" aria-hidden="true">
            <path
              d="m8.25 4.5 7.5 7.5-7.5 7.5"
              fill="none"
              stroke="currentColor"
              stroke-width="1.75"
              stroke-linecap="round"
              stroke-linejoin="round"
            />
          </svg>
        </button>
      </div>

      <div forCarouselViewport class="car-viewport">
        <div forCarouselTrack class="car-track">
          @for (slide of slides; track slide.id; let i = $index) {
            <div forCarouselSlide class="car-slide" [class]="'car-slide--' + (i + 1)">
              <p class="car-slide-title">{{ slide.title }}</p>
              <p class="car-slide-summary">{{ slide.summary }}</p>
            </div>
          }
        </div>
      </div>

      <div forCarouselIndicators class="car-indicators" ariaLabel="Choose slide to display">
        @for (slide of slides; track slide.id; let i = $index) {
          <button
            forCarouselIndicator
            class="car-dot"
            [attr.aria-label]="'Go to slide ' + (i + 1)"
          ></button>
        }
      </div>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    .car {
      display: flex;
      flex-direction: column;
      gap: 0.75rem;
      width: min(400px, 100%);
    }

    .car-controls-row {
      display: flex;
      gap: 0.5rem;
    }

    .car-btn {
      appearance: none;
      padding: 0;
      width: 32px;
      height: 32px;
      display: inline-flex;
      align-items: center;
      justify-content: center;
      border-radius: var(--ex-radius-sm, 14px);
      border: 1px solid var(--ex-border-strong, #d0c9bc);
      background: var(--ex-surface, #ffffff);
      color: var(--ex-text, #17191c);
      font-size: 1.2rem;
      line-height: 1;
      cursor: pointer;
    }

    .car-btn svg {
      width: 1em;
      height: 1em;
    }

    .car-btn:hover:not([data-disabled]) {
      background: var(--ex-surface-2, #f2eee6);
    }

    .car-btn[data-disabled] {
      opacity: 0.4;
      cursor: not-allowed;
    }

    .car-viewport {
      overflow: hidden;
      border-radius: var(--ex-radius, 22px);
      corner-shape: squircle;
    }

    .car-track {
      display: flex;
      transform: translateX(var(--for-carousel-offset));
      transition: transform 300ms ease;
    }

    @media (prefers-reduced-motion: reduce) {
      .car-track {
        transition: none;
      }
    }

    .car-slide {
      flex: 0 0 calc(100% / var(--for-carousel-slides-per-view));
      min-height: 160px;
      box-sizing: border-box;
      padding: 1.25rem 1.5rem;
      display: flex;
      flex-direction: column;
      justify-content: flex-end;
      gap: 0.35rem;
      border-radius: var(--ex-radius, 22px);
      corner-shape: squircle;
    }

    .car-slide--1 {
      background: color-mix(in srgb, var(--ex-accent, #0e7c6b) 20%, var(--ex-surface, #ffffff));
    }
    .car-slide--2 {
      background: color-mix(in srgb, var(--ex-success, #1f7a4d) 20%, var(--ex-surface, #ffffff));
    }
    .car-slide--3 {
      background: color-mix(in srgb, var(--ex-warning, #a5651a) 20%, var(--ex-surface, #ffffff));
    }
    .car-slide--4 {
      background: color-mix(in srgb, var(--ex-accent, #0e7c6b) 35%, var(--ex-surface, #ffffff));
    }
    .car-slide--5 {
      background: color-mix(in srgb, var(--ex-success, #1f7a4d) 35%, var(--ex-surface, #ffffff));
    }

    .car-slide-title {
      margin: 0;
      font-size: 1.1rem;
      font-weight: 700;
      color: var(--ex-text, #17191c);
    }

    .car-slide-summary {
      margin: 0;
      font-size: 0.9rem;
      color: var(--ex-muted, #585d66);
    }

    .car-indicators {
      display: flex;
      gap: 0.35rem;
      justify-content: center;
    }

    .car-dot {
      appearance: none;
      width: 8px;
      height: 8px;
      border-radius: 50%;
      border: none;
      background: var(--ex-border-strong, #d0c9bc);
      padding: 0;
      cursor: pointer;
      transition:
        background 0.2s ease,
        transform 0.2s ease;
    }

    .car-dot[aria-current='true'] {
      background: var(--ex-accent, #0e7c6b);
      transform: scale(1.4);
    }

    @media (prefers-reduced-motion: reduce) {
      .car-dot {
        transition: none;
      }
    }
  `,
})
export class CarouselDefaultExample {
  protected readonly slides: readonly Slide[] = [
    {
      id: 1,
      title: 'The coast road north',
      summary: 'Four days, three ferries and one small car.',
    },
    {
      id: 2,
      title: 'Markets before dawn',
      summary: 'Where the city buys its fish, flowers and coffee.',
    },
    {
      id: 3,
      title: 'A week without screens',
      summary: 'What changed, and the one habit that stuck.',
    },
    { id: 4, title: 'Bread, slowly', summary: 'A starter, a schedule and a forgiving first loaf.' },
    {
      id: 5,
      title: 'Mapping the old river',
      summary: 'Tracing a buried stream through five neighbourhoods.',
    },
  ];

  protected readonly activeIndex = signal(0);
}

Headless and styleless: it ships slide tracking, keyboard navigation, focus management, and ARIA; you supply the markup and CSS.

Anatomy

<div forCarousel [(activeIndex)]="index" loop ariaLabel="Featured products">
  <button forCarouselPrevious aria-label="Previous slide">
    <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
      <path
        d="m15.75 19.5-7.5-7.5 7.5-7.5"
        fill="none"
        stroke="currentColor"
        stroke-width="1.75"
        stroke-linecap="round"
        stroke-linejoin="round"
      />
    </svg>
  </button>

  <div forCarouselViewport>
    <div forCarouselTrack>
      <!-- one [forCarouselSlide] per item -->
      <div forCarouselSlide>Slide content</div>
    </div>
  </div>

  <button forCarouselNext aria-label="Next slide">
    <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
      <path
        d="m8.25 4.5 7.5 7.5-7.5 7.5"
        fill="none"
        stroke="currentColor"
        stroke-width="1.75"
        stroke-linecap="round"
        stroke-linejoin="round"
      />
    </svg>
  </button>

  <div forCarouselIndicators ariaLabel="Choose slide to display">
    <!-- one [forCarouselIndicator] per slide, same order -->
    <button forCarouselIndicator></button>
  </div>
</div>

Examples

Multiple slides per view

Set slidesPerView above 1 to show several slides at once. Each slide is flex: 0 0 calc(100% / var(--for-carousel-slides-per-view)); loop wraps once the last visible set is reached.

Source

Linen shirt

$48

Canvas tote

$22

Wool beanie

$19

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  ForCarousel,
  ForCarouselIndicator,
  ForCarouselIndicators,
  ForCarouselNext,
  ForCarouselPrevious,
  ForCarouselSlide,
  ForCarouselTrack,
  ForCarouselViewport,
} from 'forty-cdk/carousel';

interface Slide {
  readonly id: number;
  readonly name: string;
  readonly price: string;
}

@Component({
  selector: 'app-carousel-multiple-slides-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    ForCarousel,
    ForCarouselViewport,
    ForCarouselTrack,
    ForCarouselSlide,
    ForCarouselPrevious,
    ForCarouselNext,
    ForCarouselIndicators,
    ForCarouselIndicator,
  ],
  template: `
    <div
      forCarousel
      class="mcar"
      [(activeIndex)]="activeIndex"
      loop
      [slidesPerView]="3"
      align="start"
      ariaLabel="Product gallery"
    >
      <div class="mcar-nav-row">
        <button forCarouselPrevious class="mcar-btn" aria-label="Previous slide">
          <svg viewBox="0 0 24 24" aria-hidden="true">
            <path
              d="m15.75 19.5-7.5-7.5 7.5-7.5"
              fill="none"
              stroke="currentColor"
              stroke-width="1.75"
              stroke-linecap="round"
              stroke-linejoin="round"
            />
          </svg>
        </button>
        <button forCarouselNext class="mcar-btn" aria-label="Next slide">
          <svg viewBox="0 0 24 24" aria-hidden="true">
            <path
              d="m8.25 4.5 7.5 7.5-7.5 7.5"
              fill="none"
              stroke="currentColor"
              stroke-width="1.75"
              stroke-linecap="round"
              stroke-linejoin="round"
            />
          </svg>
        </button>
      </div>

      <div forCarouselViewport class="mcar-viewport">
        <div forCarouselTrack class="mcar-track">
          @for (slide of slides; track slide.id; let i = $index) {
            <div forCarouselSlide class="mcar-slide" [class]="'mcar-slide--' + ((i % 5) + 1)">
              <p class="mcar-slide-name">{{ slide.name }}</p>
              <p class="mcar-slide-price">{{ slide.price }}</p>
            </div>
          }
        </div>
      </div>

      <div forCarouselIndicators class="mcar-indicators" ariaLabel="Choose slide to display">
        @for (slide of slides; track slide.id; let i = $index) {
          <button
            forCarouselIndicator
            class="mcar-dot"
            [attr.aria-label]="'Go to slide ' + (i + 1)"
          ></button>
        }
      </div>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    .mcar {
      display: flex;
      flex-direction: column;
      gap: 0.75rem;
      width: min(480px, 100%);
    }

    .mcar-nav-row {
      display: flex;
      gap: 0.5rem;
    }

    .mcar-btn {
      appearance: none;
      padding: 0;
      width: 32px;
      height: 32px;
      display: inline-flex;
      align-items: center;
      justify-content: center;
      border-radius: var(--ex-radius-sm, 14px);
      border: 1px solid var(--ex-border-strong, #d0c9bc);
      background: var(--ex-surface, #ffffff);
      color: var(--ex-text, #17191c);
      font-size: 1.2rem;
      line-height: 1;
      cursor: pointer;
    }

    .mcar-btn svg {
      width: 1em;
      height: 1em;
    }

    .mcar-btn:hover:not([data-disabled]) {
      background: var(--ex-surface-2, #f2eee6);
    }

    .mcar-btn[data-disabled] {
      opacity: 0.4;
      cursor: not-allowed;
    }

    .mcar-viewport {
      overflow: hidden;
      border-radius: var(--ex-radius, 22px);
      corner-shape: squircle;
    }

    .mcar-track {
      display: flex;
      gap: 0.5rem;
      transform: translateX(var(--for-carousel-offset));
      transition: transform 300ms ease;
    }

    @media (prefers-reduced-motion: reduce) {
      .mcar-track {
        transition: none;
      }
    }

    .mcar-slide {
      flex: 0 0
        calc(
          (100% - 0.5rem * (var(--for-carousel-slides-per-view) - 1)) /
            var(--for-carousel-slides-per-view)
        );
      min-height: 120px;
      box-sizing: border-box;
      padding: 0.75rem;
      display: flex;
      flex-direction: column;
      justify-content: flex-end;
      gap: 0.15rem;
      border-radius: var(--ex-radius-sm, 14px);
    }

    .mcar-slide--1 {
      background: color-mix(in srgb, var(--ex-accent, #0e7c6b) 20%, var(--ex-surface, #ffffff));
    }
    .mcar-slide--2 {
      background: color-mix(in srgb, var(--ex-success, #1f7a4d) 20%, var(--ex-surface, #ffffff));
    }
    .mcar-slide--3 {
      background: color-mix(in srgb, var(--ex-warning, #a5651a) 20%, var(--ex-surface, #ffffff));
    }
    .mcar-slide--4 {
      background: color-mix(in srgb, var(--ex-accent, #0e7c6b) 35%, var(--ex-surface, #ffffff));
    }
    .mcar-slide--5 {
      background: color-mix(in srgb, var(--ex-success, #1f7a4d) 35%, var(--ex-surface, #ffffff));
    }

    .mcar-slide-name {
      margin: 0;
      font-size: 0.9rem;
      font-weight: 700;
      color: var(--ex-text, #17191c);
    }

    .mcar-slide-price {
      margin: 0;
      font-size: 0.85rem;
      color: var(--ex-muted, #585d66);
    }

    .mcar-indicators {
      display: flex;
      gap: 0.35rem;
      justify-content: center;
    }

    .mcar-dot {
      appearance: none;
      width: 8px;
      height: 8px;
      border-radius: 50%;
      border: none;
      background: var(--ex-border-strong, #d0c9bc);
      padding: 0;
      cursor: pointer;
      transition:
        background 0.2s ease,
        transform 0.2s ease;
    }

    .mcar-dot[aria-current='true'] {
      background: var(--ex-accent, #0e7c6b);
      transform: scale(1.4);
    }

    @media (prefers-reduced-motion: reduce) {
      .mcar-dot {
        transition: none;
      }
    }
  `,
})
export class CarouselMultipleSlidesExample {
  protected readonly slides: readonly Slide[] = [
    { id: 1, name: 'Linen shirt', price: '$48' },
    { id: 2, name: 'Canvas tote', price: '$22' },
    { id: 3, name: 'Wool beanie', price: '$19' },
    { id: 4, name: 'Leather belt', price: '$35' },
    { id: 5, name: 'Rain jacket', price: '$89' },
    { id: 6, name: 'Cotton socks', price: '$9' },
  ];

  protected readonly activeIndex = signal(0);
}

Autoplay with pause control

With autoplay set, the slides advance every three seconds, unless your system asks for reduced motion, in which case they wait for the rotation control. Hover the carousel or move focus into it and rotation pauses until you leave; stop it with the control and it stays stopped through hover and focus until you start it again. Autoplay has the full pause rules and why the control must be the first focusable child.

Source

Free shipping this week

Every order over $50 ships free until Sunday.

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  ForCarousel,
  ForCarouselIndicator,
  ForCarouselIndicators,
  ForCarouselNext,
  ForCarouselPrevious,
  ForCarouselRotationControl,
  ForCarouselSlide,
  ForCarouselTrack,
  ForCarouselViewport,
} from 'forty-cdk/carousel';

interface Slide {
  readonly id: number;
  readonly title: string;
  readonly summary: string;
}

@Component({
  selector: 'app-carousel-autoplay-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    ForCarousel,
    ForCarouselViewport,
    ForCarouselTrack,
    ForCarouselSlide,
    ForCarouselPrevious,
    ForCarouselNext,
    ForCarouselIndicators,
    ForCarouselIndicator,
    ForCarouselRotationControl,
  ],
  template: `
    <div
      forCarousel
      #car="forCarousel"
      class="acar"
      [(activeIndex)]="activeIndex"
      autoplay
      [autoplayInterval]="3000"
      loop
      ariaLabel="Auto-rotating announcements"
    >
      <button
        forCarouselRotationControl
        class="acar-rotation-btn"
        startLabel="Start automatic slide show"
        stopLabel="Stop automatic slide show"
      >
        <span class="sr-only">Toggle autoplay</span>
        @if (car.playing()) {
          <svg viewBox="0 0 24 24" aria-hidden="true">
            <path d="M8.25 5.25h3v13.5h-3zM12.75 5.25h3v13.5h-3z" fill="currentColor" />
          </svg>
        } @else {
          <svg viewBox="0 0 24 24" aria-hidden="true">
            <path d="M6.75 5.25 17.25 12 6.75 18.75z" fill="currentColor" />
          </svg>
        }
      </button>

      <div class="acar-nav-row">
        <button forCarouselPrevious class="acar-btn" aria-label="Previous slide">
          <svg viewBox="0 0 24 24" aria-hidden="true">
            <path
              d="m15.75 19.5-7.5-7.5 7.5-7.5"
              fill="none"
              stroke="currentColor"
              stroke-width="1.75"
              stroke-linecap="round"
              stroke-linejoin="round"
            />
          </svg>
        </button>
        <button forCarouselNext class="acar-btn" aria-label="Next slide">
          <svg viewBox="0 0 24 24" aria-hidden="true">
            <path
              d="m8.25 4.5 7.5 7.5-7.5 7.5"
              fill="none"
              stroke="currentColor"
              stroke-width="1.75"
              stroke-linecap="round"
              stroke-linejoin="round"
            />
          </svg>
        </button>
      </div>

      <div forCarouselViewport class="acar-viewport">
        <div forCarouselTrack class="acar-track">
          @for (slide of slides; track slide.id; let i = $index) {
            <div forCarouselSlide class="acar-slide" [class]="'acar-slide--' + (i + 1)">
              <p class="acar-slide-title">{{ slide.title }}</p>
              <p class="acar-slide-summary">{{ slide.summary }}</p>
            </div>
          }
        </div>
      </div>

      <div forCarouselIndicators class="acar-indicators" ariaLabel="Choose slide to display">
        @for (slide of slides; track slide.id; let i = $index) {
          <button
            forCarouselIndicator
            class="acar-dot"
            [attr.aria-label]="'Go to slide ' + (i + 1)"
          ></button>
        }
      </div>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    .acar {
      display: flex;
      flex-direction: column;
      gap: 0.75rem;
      width: min(400px, 100%);
    }

    .acar-rotation-btn {
      appearance: none;
      padding: 0;
      align-self: flex-start;
      width: 36px;
      height: 36px;
      display: inline-flex;
      align-items: center;
      justify-content: center;
      border-radius: var(--ex-radius-sm, 14px);
      border: 1px solid var(--ex-border-strong, #d0c9bc);
      background: var(--ex-surface, #ffffff);
      color: var(--ex-text, #17191c);
      font-size: 1.1rem;
      cursor: pointer;
    }

    .acar-rotation-btn svg {
      width: 1em;
      height: 1em;
    }

    .acar-rotation-btn:hover {
      background: var(--ex-surface-2, #f2eee6);
    }

    .sr-only {
      position: absolute;
      width: 1px;
      height: 1px;
      padding: 0;
      margin: -1px;
      overflow: hidden;
      clip: rect(0, 0, 0, 0);
      white-space: nowrap;
      border: 0;
    }

    .acar-nav-row {
      display: flex;
      gap: 0.5rem;
    }

    .acar-btn {
      appearance: none;
      padding: 0;
      width: 32px;
      height: 32px;
      display: inline-flex;
      align-items: center;
      justify-content: center;
      border-radius: var(--ex-radius-sm, 14px);
      border: 1px solid var(--ex-border-strong, #d0c9bc);
      background: var(--ex-surface, #ffffff);
      color: var(--ex-text, #17191c);
      font-size: 1.2rem;
      line-height: 1;
      cursor: pointer;
    }

    .acar-btn svg {
      width: 1em;
      height: 1em;
    }

    .acar-btn:hover:not([data-disabled]) {
      background: var(--ex-surface-2, #f2eee6);
    }

    .acar-btn[data-disabled] {
      opacity: 0.4;
      cursor: not-allowed;
    }

    .acar-viewport {
      overflow: hidden;
      border-radius: var(--ex-radius, 22px);
      corner-shape: squircle;
    }

    .acar-track {
      display: flex;
      transform: translateX(var(--for-carousel-offset));
      transition: transform 300ms ease;
    }

    @media (prefers-reduced-motion: reduce) {
      .acar-track {
        transition: none;
      }
    }

    .acar-slide {
      flex: 0 0 calc(100% / var(--for-carousel-slides-per-view));
      min-height: 160px;
      box-sizing: border-box;
      padding: 1.25rem 1.5rem;
      display: flex;
      flex-direction: column;
      justify-content: flex-end;
      gap: 0.35rem;
      border-radius: var(--ex-radius, 22px);
      corner-shape: squircle;
    }

    .acar-slide--1 {
      background: color-mix(in srgb, var(--ex-accent, #0e7c6b) 20%, var(--ex-surface, #ffffff));
    }
    .acar-slide--2 {
      background: color-mix(in srgb, var(--ex-success, #1f7a4d) 20%, var(--ex-surface, #ffffff));
    }
    .acar-slide--3 {
      background: color-mix(in srgb, var(--ex-warning, #a5651a) 20%, var(--ex-surface, #ffffff));
    }
    .acar-slide--4 {
      background: color-mix(in srgb, var(--ex-accent, #0e7c6b) 35%, var(--ex-surface, #ffffff));
    }

    .acar-slide-title {
      margin: 0;
      font-size: 1.1rem;
      font-weight: 700;
      color: var(--ex-text, #17191c);
    }

    .acar-slide-summary {
      margin: 0;
      font-size: 0.9rem;
      color: var(--ex-muted, #585d66);
    }

    .acar-indicators {
      display: flex;
      gap: 0.35rem;
      justify-content: center;
    }

    .acar-dot {
      appearance: none;
      width: 8px;
      height: 8px;
      border-radius: 50%;
      border: none;
      background: var(--ex-border-strong, #d0c9bc);
      padding: 0;
      cursor: pointer;
      transition:
        background 0.2s ease,
        transform 0.2s ease;
    }

    .acar-dot[aria-current='true'] {
      background: var(--ex-accent, #0e7c6b);
      transform: scale(1.4);
    }

    @media (prefers-reduced-motion: reduce) {
      .acar-dot {
        transition: none;
      }
    }
  `,
})
export class CarouselAutoplayExample {
  protected readonly slides: readonly Slide[] = [
    {
      id: 1,
      title: 'Free shipping this week',
      summary: 'Every order over $50 ships free until Sunday.',
    },
    { id: 2, title: 'Dark mode has landed', summary: 'Switch it on from the appearance settings.' },
    {
      id: 3,
      title: 'Planned maintenance',
      summary: 'Sign-in pauses on Sunday from 02:00 to 03:00 UTC.',
    },
    { id: 4, title: 'Spring webinars', summary: 'Four live sessions, one topic a week, all free.' },
  ];

  protected readonly activeIndex = signal(0);
}

Pointer drag & touch swipe

Add the opt-in [forCarouselDrag] directive to the viewport for pointer drag and touch swipe. The track follows the finger 1:1 via --for-carousel-swipe-movement-x/y, then snaps to the nearest slide on release.

Source

Harbour at dusk

Fishing boats back in before the lights come on.

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  ForCarousel,
  ForCarouselDrag,
  ForCarouselIndicator,
  ForCarouselIndicators,
  ForCarouselNext,
  ForCarouselPrevious,
  ForCarouselSlide,
  ForCarouselTrack,
  ForCarouselViewport,
} from 'forty-cdk/carousel';

interface Slide {
  readonly id: number;
  readonly title: string;
  readonly summary: string;
}

@Component({
  selector: 'app-carousel-drag-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    ForCarousel,
    ForCarouselViewport,
    ForCarouselDrag,
    ForCarouselTrack,
    ForCarouselSlide,
    ForCarouselPrevious,
    ForCarouselNext,
    ForCarouselIndicators,
    ForCarouselIndicator,
  ],
  template: `
    <div
      forCarousel
      class="dcar"
      [(activeIndex)]="activeIndex"
      orientation="horizontal"
      ariaLabel="Draggable gallery"
    >
      <div class="dcar-controls-row">
        <button forCarouselPrevious class="dcar-btn" aria-label="Previous slide">
          <svg viewBox="0 0 24 24" aria-hidden="true">
            <path
              d="m15.75 19.5-7.5-7.5 7.5-7.5"
              fill="none"
              stroke="currentColor"
              stroke-width="1.75"
              stroke-linecap="round"
              stroke-linejoin="round"
            />
          </svg>
        </button>
        <button forCarouselNext class="dcar-btn" aria-label="Next slide">
          <svg viewBox="0 0 24 24" aria-hidden="true">
            <path
              d="m8.25 4.5 7.5 7.5-7.5 7.5"
              fill="none"
              stroke="currentColor"
              stroke-width="1.75"
              stroke-linecap="round"
              stroke-linejoin="round"
            />
          </svg>
        </button>
      </div>

      <div forCarouselViewport forCarouselDrag class="dcar-viewport">
        <div forCarouselTrack class="dcar-track">
          @for (slide of slides; track slide.id; let i = $index) {
            <div forCarouselSlide class="dcar-slide" [class]="'dcar-slide--' + (i + 1)">
              <p class="dcar-slide-title">{{ slide.title }}</p>
              <p class="dcar-slide-summary">{{ slide.summary }}</p>
            </div>
          }
        </div>
      </div>

      <div forCarouselIndicators class="dcar-indicators" ariaLabel="Choose slide to display">
        @for (slide of slides; track slide.id; let i = $index) {
          <button
            forCarouselIndicator
            class="dcar-dot"
            [attr.aria-label]="'Go to slide ' + (i + 1)"
          ></button>
        }
      </div>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    .dcar {
      display: flex;
      flex-direction: column;
      gap: 0.75rem;
      width: min(400px, 100%);
    }

    .dcar-controls-row {
      display: flex;
      gap: 0.5rem;
    }

    .dcar-btn {
      appearance: none;
      padding: 0;
      width: 32px;
      height: 32px;
      display: inline-flex;
      align-items: center;
      justify-content: center;
      border-radius: var(--ex-radius-sm, 14px);
      border: 1px solid var(--ex-border-strong, #d0c9bc);
      background: var(--ex-surface, #ffffff);
      color: var(--ex-text, #17191c);
      font-size: 1.2rem;
      line-height: 1;
      cursor: pointer;
    }

    .dcar-btn svg {
      width: 1em;
      height: 1em;
    }

    .dcar-btn:hover:not([data-disabled]) {
      background: var(--ex-surface-2, #f2eee6);
    }

    .dcar-btn[data-disabled] {
      opacity: 0.4;
      cursor: not-allowed;
    }

    .dcar-viewport {
      overflow: hidden;
      border-radius: var(--ex-radius, 22px);
      corner-shape: squircle;
      cursor: grab;
    }

    .dcar-viewport[data-dragging] {
      cursor: grabbing;
      user-select: none;
    }

    .dcar-track {
      display: flex;
      transform: translateX(
        calc(var(--for-carousel-offset) + var(--for-carousel-swipe-movement-x, 0px))
      );
      transition: transform 300ms ease;
    }

    .dcar-viewport[data-dragging] .dcar-track {
      transition: none;
    }

    @media (prefers-reduced-motion: reduce) {
      .dcar-track {
        transition: none;
      }
    }

    .dcar-slide {
      flex: 0 0 calc(100% / var(--for-carousel-slides-per-view));
      min-height: 160px;
      box-sizing: border-box;
      padding: 1.25rem 1.5rem;
      display: flex;
      flex-direction: column;
      justify-content: flex-end;
      gap: 0.35rem;
      border-radius: var(--ex-radius, 22px);
      corner-shape: squircle;
    }

    .dcar-slide--1 {
      background: color-mix(in srgb, var(--ex-accent, #0e7c6b) 20%, var(--ex-surface, #ffffff));
    }
    .dcar-slide--2 {
      background: color-mix(in srgb, var(--ex-success, #1f7a4d) 20%, var(--ex-surface, #ffffff));
    }
    .dcar-slide--3 {
      background: color-mix(in srgb, var(--ex-warning, #a5651a) 20%, var(--ex-surface, #ffffff));
    }
    .dcar-slide--4 {
      background: color-mix(in srgb, var(--ex-accent, #0e7c6b) 35%, var(--ex-surface, #ffffff));
    }
    .dcar-slide--5 {
      background: color-mix(in srgb, var(--ex-success, #1f7a4d) 35%, var(--ex-surface, #ffffff));
    }

    .dcar-slide-title {
      margin: 0;
      font-size: 1.1rem;
      font-weight: 700;
      color: var(--ex-text, #17191c);
    }

    .dcar-slide-summary {
      margin: 0;
      font-size: 0.9rem;
      color: var(--ex-muted, #585d66);
    }

    .dcar-indicators {
      display: flex;
      gap: 0.35rem;
      justify-content: center;
    }

    .dcar-dot {
      appearance: none;
      width: 8px;
      height: 8px;
      border-radius: 50%;
      border: none;
      background: var(--ex-border-strong, #d0c9bc);
      padding: 0;
      cursor: pointer;
      transition:
        background 0.2s ease,
        transform 0.2s ease;
    }

    .dcar-dot[aria-current='true'] {
      background: var(--ex-accent, #0e7c6b);
      transform: scale(1.4);
    }

    @media (prefers-reduced-motion: reduce) {
      .dcar-dot {
        transition: none;
      }
    }
  `,
})
export class CarouselDragExample {
  protected readonly slides: readonly Slide[] = [
    {
      id: 1,
      title: 'Harbour at dusk',
      summary: 'Fishing boats back in before the lights come on.',
    },
    { id: 2, title: 'Pine ridge', summary: 'The last climb of the trail, above the tree line.' },
    { id: 3, title: 'Salt flats', summary: 'A white horizon that turns pink at sunrise.' },
    {
      id: 4,
      title: 'Old town steps',
      summary: 'Two hundred stairs between the market and the fort.',
    },
    { id: 5, title: 'Glacier lake', summary: 'Still water, cold enough to hurt your hands.' },
  ];

  protected readonly activeIndex = signal(0);
}

Autoplay

Add the autoplay attribute and a [forCarouselRotationControl] as the first focusable child of the carousel to enable automatic slide rotation.

<div forCarousel autoplay [autoplayInterval]="4000" ariaLabel="Featured products">
  <button forCarouselRotationControl>
    <svg class="icon-play" viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
      <path d="M6.75 5.25 17.25 12 6.75 18.75z" fill="currentColor" />
    </svg>
    <svg class="icon-pause" viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
      <path d="M8.25 5.25h3v13.5h-3zM12.75 5.25h3v13.5h-3z" fill="currentColor" />
    </svg>
  </button>
  <button forCarouselPrevious aria-label="Previous slide">
    <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
      <path
        d="m15.75 19.5-7.5-7.5 7.5-7.5"
        fill="none"
        stroke="currentColor"
        stroke-width="1.75"
        stroke-linecap="round"
        stroke-linejoin="round"
      />
    </svg>
  </button>
  <div forCarouselViewport>…</div>
  <button forCarouselNext aria-label="Next slide">
    <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
      <path
        d="m8.25 4.5 7.5 7.5-7.5 7.5"
        fill="none"
        stroke="currentColor"
        stroke-width="1.75"
        stroke-linecap="round"
        stroke-linejoin="round"
      />
    </svg>
  </button>
  <div forCarouselIndicators ariaLabel="Choose slide to display">…</div>
</div>

Behaviour:

Rotation pauses on hover, on keyboard focus anywhere inside the carousel, and while the browser tab is backgrounded. It resumes when none of those hold.
An explicit user stop (clicking the rotation control or calling pause()) is sticky: hover-in/out and focus-in/out will not restart it. Only an explicit Start does.
Under prefers-reduced-motion: reduce, rotation does not auto-start. The user can still start it manually by clicking the rotation control (explicit consent overrides the gate).
While rotating, the viewport's aria-live is "off" (so advancing slides do not bombard the screen reader). When stopped or paused it is "polite" so manual navigation is announced.

APG requirement: if you enable autoplay, you must render a [forCarouselRotationControl] and place it first in the tab order, because an auto-rotating carousel without a visible pause control fails WCAG 2.2.2 (Pause, Stop, Hide). The directive does not enforce this, but your implementation does.

Label inputs: the control uses a label swap, not aria-pressed. Override the defaults with startLabel / stopLabel inputs:

<button forCarouselRotationControl startLabel="Play slideshow" stopLabel="Pause slideshow"></button>

Both defaults come from the scope's rotationStartLabel / rotationStopLabel (see Localizing the default labels); set either input to null when the button carries a visible text label and you don't want an aria-label overriding it.

Programmatic control via exportAs:

<div forCarousel #car="forCarousel" autoplay>…</div>

car.play(); // start (explicit, sticky)
car.pause(); // stop (explicit, sticky)
car.toggleAutoplay(); // toggle
car.playing(); // Signal<boolean> — user intent

Drag / swipe

Apply forCarouselDrag on the [forCarouselViewport] element to enable pointer drag and touch swipe navigation. The directive is opt-in and tree-shakeable: it adds nothing to the root ForCarousel for consumers who don't use it.

<div forCarousel [(activeIndex)]="index" ariaLabel="Featured products">
  <div forCarouselViewport forCarouselDrag>
    <div forCarouselTrack>…</div>
  </div>
  <!-- prev / next / indicators as before -->
</div>

CSS contract

The directive publishes the live displacement as --for-carousel-swipe-movement-x (horizontal carousels) or --for-carousel-swipe-movement-y (vertical), a raw px value on the viewport host; only the primary-axis property is written. Compose it with --for-carousel-offset on the track transform:

[forCarouselTrack] {
  transform: translateX(
    calc(var(--for-carousel-offset) + var(--for-carousel-swipe-movement-x, 0px))
  );
  transition: transform 300ms ease;
}
[forCarousel][data-orientation='vertical'] [forCarouselTrack] {
  transform: translateY(
    calc(var(--for-carousel-offset) + var(--for-carousel-swipe-movement-y, 0px))
  );
}
/* Kill the settle transition while the finger is down so the track follows 1:1 */
[forCarouselViewport][data-dragging] [forCarouselTrack] {
  transition: none;
}
[forCarouselViewport][data-dragging] {
  user-select: none;
}

RTL

--for-carousel-swipe-movement-x is always the physical finger displacement, so compose it without the -1 factor the consumer may apply to --for-carousel-offset in RTL:

[dir='rtl'] [forCarouselTrack] {
  transform: translateX(
    calc(-1 * var(--for-carousel-offset) + var(--for-carousel-swipe-movement-x, 0px))
  );
}

Reduced motion

Under prefers-reduced-motion: reduce the directive does not publish --for-carousel-swipe-movement-x / -y (no live track motion). The gesture still snaps activeIndex on release. Only the continuous live offset is suppressed.

Cross-axis / touch

touch-action is set automatically on the viewport host: pan-y for horizontal carousels (allows vertical page scroll) and pan-x for vertical carousels (allows horizontal page scroll). A mostly-cross-axis swipe is never captured, so page scrolling on the perpendicular axis is unaffected.

Localizing the default labels

Each slide's default aria-label is the positional "N of M" string, each indicator's is "Go to slide N", and the rotation control's swaps between "Start automatic slide show" and "Stop automatic slide show". The root and each slide also carry an aria-roledescription ("carousel" / "slide"), which a screen reader speaks in place of the group role. Localize them all centrally with provideForCarouselDefaults instead of setting ariaLabel on every slide and indicator:

providers: [
  provideForCarouselDefaults({
    slideLabel: (position, total) => `Diapositiva ${position} de ${total}`,
    indicatorLabel: (position) => `Ir a la diapositiva ${position}`,
    rotationStartLabel: 'Iniciar la presentación',
    rotationStopLabel: 'Detener la presentación',
    roleDescription: 'carrusel',
    slideRoleDescription: 'diapositiva',
  }),
];

position is the 1-based slide index and total is the slide count. Overrides merge with the parent scope, so you can localize just the labels and inherit the rest of the defaults. A per-element ariaLabel on [forCarouselSlide] / [forCarouselIndicator] still takes precedence over the localized default, as do [startLabel] / [stopLabel] on [forCarouselRotationControl]. For a language the app sets or switches after bootstrap, pass the text keys as functions and the overrides as a factory, as Localizing default text shows.

Indicators map 1:1 to slides

The picker assumes one [forCarouselIndicator] per [forCarouselSlide]: the indicator at DOM index i targets slide i. Iterate the same collection that drives the slides so the counts always match. A mismatched count desynchronizes the active-indicator state and is dev-guarded by a console.warn in development builds. Grouped or summarized indicators (fewer dots than slides) are not supported.

API

`ForCarousel`

All inputs are on [forCarousel] unless noted.

Property	Type	Description
`activeIndex`	`model`	Two-way bindable current slide index. Default: `0`
`orientation`	`'horizontal' \| 'vertical'`	Scroll axis. Default: `'horizontal'`
`loop`	`boolean`	Wrap-around at the boundaries. Default: `false`
`align`	`'start' \| 'center' \| 'end'`	Alignment of the active slide. Default: `'start'`
`slidesPerView`	`number`	Visible slides at once. Default: `1`
`containScroll`	`boolean`	Clamp the track offset so trailing slides sit flush at the viewport edge (no overscroll) when `slidesPerView > 1` and not looping. Default: `false`
`autoplay`	`boolean`	Enable auto-rotation (suppressed by `prefers-reduced-motion: reduce`). Default: `false`
`autoplayInterval`	`number`	Ms between automatic slide advances. `<= 0` disables the timer. Default: `5000`
`ariaLabel`	`string \| null`	Accessible label for the carousel root. Default: `null`
`dir`	`'ltr' \| 'rtl' \| null`	Writing direction. Default: `null` (inherits)
`ariaLabel` (on `[forCarouselIndicators]`)	`string \| null`	Label for the picker group. Default: `null`
`ariaLabel` (on `[forCarouselSlide]`)	`string \| null`	Override the positional "N of M" label. Default: `null`
`disabled` (on `[forCarouselIndicator]`)	`boolean`	Disable this indicator. Default: `false`
`startLabel` (on `[forCarouselRotationControl]`)	`string \| null`	Accessible name while rotation is stopped. Default: scope `rotationStartLabel` (`'Start automatic slide show'`)
`stopLabel` (on `[forCarouselRotationControl]`)	`string \| null`	Accessible name while rotation is playing. Default: scope `rotationStopLabel` (`'Stop automatic slide show'`)

Reflected on the [forCarousel] host:

Data attribute	Values
`data-orientation`	`horizontal` \| `vertical`
`data-align`	`start` \| `center` \| `end`
`data-autoplay`	present when `autoplay` is `true`
`data-rotating`	present while actively rotating

Contain scroll

With slidesPerView > 1, align="start", and no loop, advancing to the last slide overscrolls the track: the final page may show only one real slide followed by empty space. Adding the containScroll attribute to [forCarousel] clamps --for-carousel-offset so the last visible page always sits flush at the viewport's trailing edge:

<div forCarousel containScroll [slidesPerView]="3" ariaLabel="Featured products">…</div>

Every slide still has its own indicator; trailing indicators that would map to the same clamped view simply share the same visual position. The clamp has no effect when loop is enabled (the entire range is valid when wrapping) or when slidesPerView is 1 (a single-view carousel never overscrolls).

`ForCarouselDrag` inputs

Property	Type	Description
`disabled`	`boolean`	Disable pointer drag without removing the directive. Removes `touch-action`. Default: `false`

Reflected on the [forCarouselViewport] host this directive is applied to:

Data attribute	Values
`data-dragging`	present while a drag gesture is armed

Keyboard

Keyboard navigation lives on the indicator group. Only the current indicator is in the tab order. Arrow keys move focus and activate the target slide automatically.

Key	Action
`ArrowRight` / `ArrowLeft`	Next / previous indicator (horizontal). In RTL, direction is swapped.
`ArrowDown` / `ArrowUp`	Next / previous indicator (vertical orientation).
`Home`	First indicator and slide.
`End`	Last indicator and slide.
`Enter` / `Space`	Activate the focused indicator (via native button).

Accessibility

Implements the WAI-ARIA Carousel pattern.

The root carries role="group" and aria-roledescription="carousel". The ariaLabel input should describe the carousel's purpose without using the word "carousel" (APG guidance).
Each slide carries role="group", aria-roledescription="slide", and aria-label="N of M" by default. Override per slide with the ariaLabel input, or localize the default format and both role descriptions app-wide with provideForCarouselDefaults (see Localizing the default labels).
Off-view slides receive aria-hidden="true" and inert to remove them from the accessibility tree and focus order.
The indicator group should be labelled (e.g. ariaLabel="Choose slide to display").
The current indicator is marked with aria-current="true".
Prev/next buttons never use the native disabled attribute. At a boundary without loop they reflect aria-disabled="true" + data-disabled and ignore activation, so a keyboard user who reaches the last slide keeps focus on the button instead of being dropped to <body>. Style the boundary state off [data-disabled], never :disabled.
The viewport carries aria-live and aria-atomic="false". While the carousel is actively auto-rotating, aria-live is "off" so advancing slides do not bombard the screen reader. When stopped or paused, it is "polite" so manual navigation announces. The per-slide aria-roledescription, aria-label, and aria-hidden toggle carry the screen-reader experience for non-auto-rotating carousels.

Styling

forty-cdk ships no styles: put your own class on each piece rather than styling the for* selectors (Styling forty-cdk explains why). The directive publishes geometry as CSS custom properties on the root element so they cascade to the track. The consumer applies the transform and transition.

[forCarouselViewport] {
  overflow: hidden;
}
[forCarouselTrack] {
  display: flex;
  transform: translateX(var(--for-carousel-offset));
  transition: transform 300ms ease;
}
[forCarousel][data-orientation='vertical'] [forCarouselTrack] {
  flex-direction: column;
  transform: translateY(var(--for-carousel-offset));
}
[forCarouselSlide] {
  flex: 0 0 calc(100% / var(--for-carousel-slides-per-view));
}
@media (prefers-reduced-motion: reduce) {
  [forCarouselTrack] {
    transition: none;
  }
}

CSS custom properties

The following properties are set on the [forCarousel] host and cascade to children, unless noted otherwise:

Property	Host	Value	Notes
`--for-carousel-offset`	`[forCarousel]`	e.g. `-100%`	Pure arithmetic from `activeIndex`, `slidesPerView`, `align`.
`--for-carousel-active-index`	`[forCarousel]`	integer	Current `activeIndex`.
`--for-carousel-slide-count`	`[forCarousel]`	integer	Total registered slides.
`--for-carousel-slides-per-view`	`[forCarousel]`	integer	From the `slidesPerView` input.
`--for-carousel-viewport-width`	`[forCarousel]`	e.g. `640px`	Measured via `ResizeObserver`. Absent on the server and before first measurement.
`--for-carousel-viewport-height`	`[forCarousel]`	e.g. `400px`	Same as above, for the block axis.
`--for-carousel-swipe-movement-x`	`[forCarouselViewport]`	e.g. `-128px`	Live px displacement along the primary axis during a swipe. Only the axis matching `orientation` is written; the other is absent, as is both at rest and under `prefers-reduced-motion: reduce`.
`--for-carousel-swipe-movement-y`	`[forCarouselViewport]`	e.g. `-128px`	Live px displacement along the primary axis during a swipe. Only the axis matching `orientation` is written; the other is absent, as is both at rest and under `prefers-reduced-motion: reduce`.

Autoplay styling hooks

Render both icons inside the control and let data-playing pick which one shows. The control keeps its own accessible name either way, so the icons stay aria-hidden.

[forCarouselRotationControl] .icon-pause,
[forCarouselRotationControl][data-playing] .icon-play {
  display: none;
}
[forCarouselRotationControl][data-playing] .icon-pause {
  display: revert;
}

Attribute	When present
`data-playing`	On `[forCarouselRotationControl]` when user intent is "on"
`data-rotating`	On `[forCarousel]` while it is actively rotating
`data-autoplay`	On `[forCarousel]` when the `autoplay` input is `true`

Boundary styling hooks

Attribute	When present
`data-disabled`	On `[forCarouselPrevious]` when at index 0 without `loop`
`data-disabled`	On `[forCarouselNext]` when at the last index without `loop`

Drag styling hooks

Attribute	Host	When present
`data-dragging`	`[forCarouselViewport]`	Present while a drag gesture is armed.

Reduced-motion styling

The directive performs no animation itself. Add the following CSS to disable the transition for users who prefer reduced motion:

@media (prefers-reduced-motion: reduce) {
  [forCarouselTrack] {
    transition: none;
  }
}

RTL support

Arrow-key direction (ArrowLeft/ArrowRight) is automatically swapped in RTL by resolveListNavigation and the reflected dir attribute. The visual track direction in RTL is the consumer's CSS concern. For example, to flip the translate sign in RTL:

[dir='rtl'] [forCarouselTrack] {
  transform: translateX(calc(-1 * var(--for-carousel-offset)));
}

The example CSS above is LTR-only by default.

Wrapping in a design system

Subclass the root and re-provide FOR_CAROUSEL_CONTEXT with useExisting pointing at the subclass, since Angular does not inherit a directive's providers; Wrapping non-form roots walks the pattern.

Anatomy

Examples

Autoplay

Drag / swipe

CSS contract

RTL

Reduced motion

Cross-axis / touch

Localizing the default labels

Indicators map 1:1 to slides

API

ForCarousel

Contain scroll

ForCarouselDrag inputs

Keyboard

Accessibility

Styling

CSS custom properties

Autoplay styling hooks

Boundary styling hooks

Drag styling hooks

Reduced-motion styling

RTL support

Wrapping in a design system

`ForCarousel`

`ForCarouselDrag` inputs