shadcn-rails

Carousel

A carousel with motion and swipe built using Stimulus.

Stimulus: shadcn--carousel
1
2
3
4
5

Installation

Add the component to your project:

rails generate shadcn:component carousel

Usage

<%= render Shadcn::CarouselComponent.new do |carousel| %>
  <% carousel.with_slides do |slides| %>
    <% 5.times do |i| %>
      <% slides.with_item do %>
        <div class="p-6 text-center bg-muted rounded-lg">
          Slide <%= i + 1 %>
        </div>
      <% end %>
    <% end %>
  <% end %>
  <% carousel.with_previous %>
  <% carousel.with_next %>
<% end %>

Examples

With Images

Display images in a carousel.

Image 1
Image 2
Image 3

Custom Item Sizes

Use the basis prop on items to show multiple slides at once.

1
2
3
4
5
6
7
8

Vertical Orientation

Use orientation: :vertical for vertical carousels.

1
2
3
4
5

Infinite Loop

Enable infinite looping with the loop option.

1
2
3
4
5

Autoplay

Automatically advance slides with the autoplay option.

1
2
3
4
5

With Card Content

Carousel items can contain any content, including cards.

Getting Started

Learn the basics of the framework

Content goes here

Components

Explore our component library

Content goes here

Theming

Customize colors and styles

Content goes here

API Reference

API Reference

Prop Type Default Description
orientation Symbol :horizontal Direction of carousel (:horizontal, :vertical)
loop Boolean false Whether to loop infinitely
autoplay Boolean false Whether to auto-advance slides
autoplay_interval Integer 4000 Milliseconds between auto-advance
align Symbol :start Item alignment (:start, :center, :end)
class_name String nil Additional CSS classes

Slots

Slot Description
with_slides Container for carousel items
slides.with_item(basis:) Individual carousel item. Use basis for custom widths
with_previous Previous slide button
with_next Next slide button

Stimulus Controller

This component requires JavaScript. The Stimulus controller docs provides interactivity.

Manages carousel navigation, autoplay, keyboard navigation, and touch/swipe gestures.

Installation

Add to your config/importmap.rb:

pin "shadcn-rails", to: "shadcn/index.js"

Then in your app/javascript/controllers/index.js:

import { Application } from "@hotwired/stimulus"
import { registerShadcnControllers } from "shadcn-rails"

const application = Application.start()
registerShadcnControllers(application)

Or import just this controller:

import DocsController from "shadcn-rails/controllers/docs_controller"

application.register("docs", DocsController)

Values

Name Type Default Description
orientation String Direction (horizontal or vertical)
loop Boolean Whether to loop infinitely
autoplay Boolean Whether to auto-advance
autoplayInterval Number Milliseconds between auto-advance
align String Item alignment (start, center, end)
selectedIndex Number Currently selected slide index

Actions

Action Description
previous Go to the previous slide
next Go to the next slide
goToSlide Go to a specific slide by index (use data-index)

TypeScript

Type definitions are included. Import types as needed: 

import type { DocsController } from "shadcn-rails"

Accessibility

  • Uses role="region" with aria-roledescription="carousel"
  • Each slide has role="group" with aria-roledescription="slide"
  • Non-visible slides are marked with aria-hidden="true" and inert
  • Keyboard navigation: Arrow Left/Right (horizontal) or Up/Down (vertical)
  • Touch/swipe support on mobile devices
  • Autoplay pauses on hover and touch interaction