Carousel

Guidelines
React API Reference

Carousels present multiple pieces of content in a compact, horizontally or vertically scrollable format, allowing users to browse through items efficiently while maintaining focus on individual content pieces.

Guidance

Aspect	Best Practice
Usage	Use carousels to showcase multiple related items, featured content, or when space is limited and progressive disclosure is beneficial.
Content	Ensure each carousel item is self-contained and meaningful. Maintain consistent sizing and content hierarchy across items.
Behavior	Provide clear navigation controls. Support both mouse/touch interactions and keyboard navigation. Implement smooth, predictable transitions.
States	Clearly indicate current position and available navigation options. Disable navigation buttons when at boundaries.
Feedback	Use visual indicators like dots or arrows to show navigation state. Provide accessible labels for navigation controls.
Examples	Product showcases, image galleries, testimonials, featured articles, or any collection where users benefit from browsing one item at a time.

Best Practices

Consistent Item Sizing: Maintain uniform dimensions for a polished appearance.
Clear Navigation: Provide intuitive navigation controls that are easily accessible.
Keyboard Support: Ensure full keyboard accessibility with arrow key navigation.
Responsive Design: Adapt to different screen sizes and orientations appropriately.
Performance: Optimize for smooth scrolling and minimal layout shifts.

Do’s and Don’ts

Do

Provide clear navigation controls and indicators. * Support keyboard navigation (arrow keys). * Use consistent item sizing and spacing. * Include accessible labels for screen readers. * Optimize for touch interactions on mobile devices.

Don't

Auto-advance without user control or clear indication. * Hide critical content that users might miss. * Use carousels for primary navigation or essential information. * Overcrowd items or make navigation controls too small.

Additional Guidance

Psychological Impact:
- Focus: Carousels help users focus on individual items without overwhelming choices.
- Discovery: Enable content exploration in a structured, predictable manner.
- Engagement: Interactive navigation keeps users engaged with the content.
Accessibility Considerations:
- Implement proper ARIA labels and roles
- Ensure keyboard navigation works intuitively
- Provide alternative ways to access all content
- Consider users with motion sensitivity preferences

Import

import{" "}

{(Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext)}{" "}
from '@strongtie/design-system/carousel'; ```
</Step>
<Step title="Usage">
```jsx
<Carousel>
  <CarouselContent>
    <CarouselItem>
      <div>Slide 1</div>
    </CarouselItem>
    <CarouselItem>
      <div>Slide 2</div>
    </CarouselItem>
    <CarouselItem>
      <div>Slide 3</div>
    </CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

`<Carousel>` Props

orientation

"horizontal" | "vertical"

default:"\"horizontal\""

The orientation of the carousel. Determines scroll direction and navigation button positioning.

opts

EmblaOptionsType

Configuration options for the underlying Embla Carousel. Includes options like loop, align, slidesToScroll, etc.

plugins

EmblaPluginType[]

Array of Embla Carousel plugins to extend functionality.

setApi

(api: CarouselApi) => void

Callback function that receives the carousel API instance for programmatic control.

`<CarouselPrevious>` Props

Implements all Button Props

`<CarouselNext>` Props

Implements all Button Props

Usage Examples

<Carousel>
  <CarouselContent>
    <CarouselItem>
      <div>
        <h3>Slide 1</h3>
        <p>Content for slide 1</p>
      </div>
    </CarouselItem>
    <CarouselItem>
      <div>
        <h3>Slide 2</h3>
        <p>Content for slide 2</p>
      </div>
    </CarouselItem>
    <CarouselItem>
      <div>
        <h3>Slide 3</h3>
        <p>Content for slide 3</p>
      </div>
    </CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

Carousel API

When using setApi, you gain access to the Embla Carousel API with methods like:

scrollNext() - Navigate to next slide
scrollPrev() - Navigate to previous slide
scrollTo(index) - Navigate to specific slide
canScrollNext() - Check if can scroll forward
canScrollPrev() - Check if can scroll backward
selectedScrollSnap() - Get current slide index
scrollSnapList() - Get array of all scroll snap positions

Styling Classes

The following CSS classes are applied by the Carousel components:

carousel – Root carousel container.
carousel-content – Overflow container for carousel items.
carousel-content-items – Flex container for items with orientation modifiers.
carousel-item – Individual carousel item wrapper.
carousel-previous – Previous navigation button.
carousel-next – Next navigation button.

Orientation modifiers:

-horizontal – Applied for horizontal orientation.
-vertical – Applied for vertical orientation.

For more examples, visit the Storybook.

Getting Started

Foundations

Components

Integration Guides

Content

Guidance

Best Practices

Do’s and Don’ts

Do

Don't

Additional Guidance

`<Carousel>` Props

`<CarouselPrevious>` Props

`<CarouselNext>` Props

Usage Examples

Carousel API

Styling Classes

Getting Started

Foundations

Components

Integration Guides

Content

​Guidance

​Best Practices

​Do’s and Don’ts

Do

Don't

​Additional Guidance

​<Carousel> Props

​<CarouselPrevious> Props

​<CarouselNext> Props

​Usage Examples

​Carousel API

​Styling Classes

Guidance

Best Practices

Do’s and Don’ts

Additional Guidance

`<Carousel>` Props

`<CarouselPrevious>` Props

`<CarouselNext>` Props

Usage Examples

Carousel API

Styling Classes