Carousel
A carousel with motion and swipe built using Embla.
Usage
Example
Carousel is a region, and a region needs a name: give it an aria_label (or aria_labelledby pointing at a visible heading). Previous and Next disable at the first and last slide.
Carousel(aria_label: "Numbers", class: "w-full max-w-xs") do
CarouselContent do
5.times do |index|
CarouselItem do
div(class: "p-1") do
Card(class: "py-0") do
CardContent(class: "flex aspect-square items-center justify-center p-6") do
span(class: "text-4xl font-semibold") { index + 1 }
end
end
end
end
end
end
CarouselPrevious()
CarouselNext()
end
Sizes
Carousel(aria_label: "Numbers", class: "w-full max-w-sm") do
CarouselContent do
5.times do |index|
CarouselItem(class: "md:basis-1/2 lg:basis-1/3") do
div(class: "p-1") do
Card(class: "py-0") do
CardContent(class: "flex aspect-square items-center justify-center p-6") do
span(class: "text-3xl font-semibold") { index + 1 }
end
end
end
end
end
end
CarouselPrevious()
CarouselNext()
end
Spacing
Carousel(aria_label: "Numbers", class: "w-full max-w-sm") do
CarouselContent(class: "-ml-1") do
5.times do |index|
CarouselItem(class: "pl-1 md:basis-1/2 lg:basis-1/3") do
div(class: "p-1") do
Card(class: "py-0") do
CardContent(class: "flex aspect-square items-center justify-center p-6") do
span(class: "text-2xl font-semibold") { index + 1 }
end
end
end
end
end
end
CarouselPrevious()
CarouselNext()
end
Orientation
Carousel(orientation: :vertical, options: {align: "start"}, aria_label: "Numbers", class: "w-full max-w-xs") do
CarouselContent(class: "-mt-1 h-[200px]") do
5.times do |index|
CarouselItem(class: "pt-1 md:basis-1/2") do
div(class: "p-1") do
Card(class: "py-0") do
CardContent(class: "flex items-center justify-center p-6") do
span(class: "text-3xl font-semibold") { index + 1 }
end
end
end
end
end
end
CarouselPrevious()
CarouselNext()
end
Loop
options: takes JSON-compatible Embla options. With loop: true the carousel wraps from the last slide to the first, so Previous and Next never disable.
Carousel(options: {loop: true}, aria_label: "Numbers", class: "w-full max-w-xs") do
CarouselContent do
5.times do |index|
CarouselItem do
div(class: "p-1") do
Card(class: "py-0") do
CardContent(class: "flex aspect-square items-center justify-center p-6") do
span(class: "text-4xl font-semibold") { index + 1 }
end
end
end
end
end
end
CarouselPrevious()
CarouselNext()
end
Installation
Using RubyUI CLI
Run the install command
rails g ruby_ui:component Carousel
Manual installation
1
Add RubyUI::Carousel to app/components/ruby_ui/carousel/carousel.rb
# frozen_string_literal: true
module RubyUI
# Embla carousel. The orientation reaches CarouselContent, CarouselItem,
# CarouselPrevious and CarouselNext through the render context, so their
# orientation classes are plain utilities a caller's class can override
# (shadcn's cn behavior).
class Carousel < Base
VALID_ORIENTATIONS = %i[horizontal vertical].freeze
def initialize(orientation: :horizontal, options: {}, **user_attrs)
@orientation = orientation.to_s.to_sym
raise ArgumentError, "orientation must be :horizontal or :vertical" unless VALID_ORIENTATIONS.include?(@orientation)
@options = options
super(**user_attrs)
end
def view_template(&)
previous = context[:ruby_ui_carousel]
context[:ruby_ui_carousel] = {orientation: @orientation}
div(**attrs, &)
ensure
context[:ruby_ui_carousel] = previous
end
private
def default_attrs
{
class: ["relative group", orientation_classes],
role: "region",
aria_roledescription: "carousel",
data: {
slot: "carousel",
controller: "ruby-ui--carousel",
ruby_ui__carousel_options_value: default_options.merge(@options).to_json,
action: %w[
keydown.right->ruby-ui--carousel#scrollNext:prevent
keydown.left->ruby-ui--carousel#scrollPrev:prevent
]
}
}
end
def default_options
{
axis: (@orientation == :horizontal) ? "x" : "y"
}
end
def orientation_classes
(@orientation == :horizontal) ? "is-horizontal" : "is-vertical"
end
end
end
2
Add RubyUI::CarouselContent to app/components/ruby_ui/carousel/carousel_content.rb
# frozen_string_literal: true
module RubyUI
class CarouselContent < Base
ORIENTATION_CLASSES = {horizontal: "-ml-4", vertical: "-mt-4 flex-col"}.freeze
def view_template(&)
div(class: "overflow-hidden", data: {slot: "carousel-content", ruby_ui__carousel_target: "viewport"}) do
div(**attrs, class: TAILWIND_MERGER.merge([ORIENTATION_CLASSES.fetch(orientation), attrs[:class]]), &)
end
end
private
def orientation
context.dig(:ruby_ui_carousel, :orientation) || :horizontal
end
def default_attrs
{class: "flex"}
end
end
end
3
Add RubyUI::CarouselDocs to app/components/ruby_ui/carousel/carousel_docs.rb
# frozen_string_literal: true
class Views::Docs::Carousel < Views::Base
def view_template
component = "Carousel"
div(class: "max-w-2xl mx-auto w-full py-10 space-y-10") do
render Docs::Header.new(title: "Carousel", description: "A carousel with motion and swipe built using Embla.")
Heading(level: 2) { "Usage" }
render Docs::VisualCodeExample.new(title: "Example", description: "Carousel is a region, and a region needs a name: give it an aria_label (or aria_labelledby pointing at a visible heading). Previous and Next disable at the first and last slide.", context: self) do
<<~RUBY
Carousel(aria_label: "Numbers", class: "w-full max-w-xs") do
CarouselContent do
5.times do |index|
CarouselItem do
div(class: "p-1") do
Card(class: "py-0") do
CardContent(class: "flex aspect-square items-center justify-center p-6") do
span(class: "text-4xl font-semibold") { index + 1 }
end
end
end
end
end
end
CarouselPrevious()
CarouselNext()
end
RUBY
end
render Docs::VisualCodeExample.new(title: "Sizes", context: self) do
<<~RUBY
Carousel(aria_label: "Numbers", class: "w-full max-w-sm") do
CarouselContent do
5.times do |index|
CarouselItem(class: "md:basis-1/2 lg:basis-1/3") do
div(class: "p-1") do
Card(class: "py-0") do
CardContent(class: "flex aspect-square items-center justify-center p-6") do
span(class: "text-3xl font-semibold") { index + 1 }
end
end
end
end
end
end
CarouselPrevious()
CarouselNext()
end
RUBY
end
render Docs::VisualCodeExample.new(title: "Spacing", context: self) do
<<~RUBY
Carousel(aria_label: "Numbers", class: "w-full max-w-sm") do
CarouselContent(class: "-ml-1") do
5.times do |index|
CarouselItem(class: "pl-1 md:basis-1/2 lg:basis-1/3") do
div(class: "p-1") do
Card(class: "py-0") do
CardContent(class: "flex aspect-square items-center justify-center p-6") do
span(class: "text-2xl font-semibold") { index + 1 }
end
end
end
end
end
end
CarouselPrevious()
CarouselNext()
end
RUBY
end
render Docs::VisualCodeExample.new(title: "Orientation", context: self) do
<<~RUBY
Carousel(orientation: :vertical, options: {align: "start"}, aria_label: "Numbers", class: "w-full max-w-xs") do
CarouselContent(class: "-mt-1 h-[200px]") do
5.times do |index|
CarouselItem(class: "pt-1 md:basis-1/2") do
div(class: "p-1") do
Card(class: "py-0") do
CardContent(class: "flex items-center justify-center p-6") do
span(class: "text-3xl font-semibold") { index + 1 }
end
end
end
end
end
end
CarouselPrevious()
CarouselNext()
end
RUBY
end
render Docs::VisualCodeExample.new(title: "Loop", description: "options: takes JSON-compatible Embla options. With loop: true the carousel wraps from the last slide to the first, so Previous and Next never disable.", context: self) do
<<~RUBY
Carousel(options: {loop: true}, aria_label: "Numbers", class: "w-full max-w-xs") do
CarouselContent do
5.times do |index|
CarouselItem do
div(class: "p-1") do
Card(class: "py-0") do
CardContent(class: "flex aspect-square items-center justify-center p-6") do
span(class: "text-4xl font-semibold") { index + 1 }
end
end
end
end
end
end
CarouselPrevious()
CarouselNext()
end
RUBY
end
render Components::ComponentSetup::Tabs.new(component_name: component)
render Docs::ComponentsTable.new(component_files(component))
end
end
end
4
Add RubyUI::CarouselItem to app/components/ruby_ui/carousel/carousel_item.rb
# frozen_string_literal: true
module RubyUI
class CarouselItem < Base
ORIENTATION_CLASSES = {horizontal: "pl-4", vertical: "pt-4"}.freeze
def view_template(&)
div(**attrs, class: TAILWIND_MERGER.merge([ORIENTATION_CLASSES.fetch(orientation), attrs[:class]]), &)
end
private
def orientation
context.dig(:ruby_ui_carousel, :orientation) || :horizontal
end
def default_attrs
{
role: "group",
aria_roledescription: "slide",
data: {slot: "carousel-item"},
class: "min-w-0 shrink-0 grow-0 basis-full"
}
end
end
end
5
Add RubyUI::CarouselNext to app/components/ruby_ui/carousel/carousel_next.rb
# frozen_string_literal: true
module RubyUI
class CarouselNext < Base
ORIENTATION_CLASSES = {
horizontal: "-right-12 top-1/2 -translate-y-1/2",
vertical: "-bottom-12 left-1/2 -translate-x-1/2 rotate-90"
}.freeze
def view_template
# slot! overrides Button's data-slot="button" instead of appending to it.
Button(**attrs, class: [ORIENTATION_CLASSES.fetch(orientation), attrs[:class]], data: {**attrs[:data], slot!: "carousel-next"}) do
icon
span(class: "sr-only") { "Next slide" }
end
end
private
def orientation
context.dig(:ruby_ui_carousel, :orientation) || :horizontal
end
def default_attrs
{
variant: :outline,
icon: true,
class: "absolute h-8 w-8 rounded-full touch-manipulation",
disabled: true,
data: {
action: "click->ruby-ui--carousel#scrollNext",
ruby_ui__carousel_target: "nextButton"
}
}
end
# lucide chevron-right, mirrored in RTL when horizontal.
def icon
svg(
width: "24",
height: "24",
viewBox: "0 0 24 24",
fill: "none",
stroke: "currentColor",
stroke_width: "2",
stroke_linecap: "round",
stroke_linejoin: "round",
xmlns: "http://www.w3.org/2000/svg",
aria_hidden: "true",
# Mirrored in RTL only when horizontal: the vertical axis doesn't
# depend on reading direction.
class: (orientation == :horizontal) ? "rtl:rotate-180" : nil
) do |s|
s.path(d: "m9 18 6-6-6-6")
end
end
end
end
6
Add RubyUI::CarouselPrevious to app/components/ruby_ui/carousel/carousel_previous.rb
# frozen_string_literal: true
module RubyUI
class CarouselPrevious < Base
ORIENTATION_CLASSES = {
horizontal: "-left-12 top-1/2 -translate-y-1/2",
vertical: "-top-12 left-1/2 -translate-x-1/2 rotate-90"
}.freeze
def view_template
# slot! overrides Button's data-slot="button" instead of appending to it.
Button(**attrs, class: [ORIENTATION_CLASSES.fetch(orientation), attrs[:class]], data: {**attrs[:data], slot!: "carousel-previous"}) do
icon
span(class: "sr-only") { "Previous slide" }
end
end
private
def orientation
context.dig(:ruby_ui_carousel, :orientation) || :horizontal
end
def default_attrs
{
variant: :outline,
icon: true,
class: "absolute h-8 w-8 rounded-full touch-manipulation",
disabled: true,
data: {
action: "click->ruby-ui--carousel#scrollPrev",
ruby_ui__carousel_target: "prevButton"
}
}
end
# lucide chevron-left, mirrored in RTL when horizontal.
def icon
svg(
width: "24",
height: "24",
viewBox: "0 0 24 24",
fill: "none",
stroke: "currentColor",
stroke_width: "2",
stroke_linecap: "round",
stroke_linejoin: "round",
xmlns: "http://www.w3.org/2000/svg",
aria_hidden: "true",
# Mirrored in RTL only when horizontal: the vertical axis doesn't
# depend on reading direction.
class: (orientation == :horizontal) ? "rtl:rotate-180" : nil
) do |s|
s.path(d: "m15 18-6-6 6-6")
end
end
end
end
7
Add carousel_controller.js to app/javascript/controllers/ruby_ui/carousel_controller.js
import { Controller } from "@hotwired/stimulus";
import EmblaCarousel from 'embla-carousel'
export default class extends Controller {
static values = {
options: {
type: Object,
default: {},
}
}
static targets = ["viewport", "nextButton", "prevButton"]
connect() {
this.initCarousel(this.optionsValue)
}
disconnect() {
this.destroyCarousel()
}
initCarousel(options, plugins = []) {
this.carousel = EmblaCarousel(this.viewportTarget, options, plugins)
this.carousel.on("init", this.#updateControls.bind(this))
this.carousel.on("reInit", this.#updateControls.bind(this))
this.carousel.on("select", this.#updateControls.bind(this))
}
destroyCarousel() {
this.carousel.destroy()
}
scrollNext() {
this.carousel.scrollNext()
}
scrollPrev() {
this.carousel.scrollPrev()
}
#updateControls() {
this.#toggleButtonsDisabledState(this.nextButtonTargets, !this.carousel.canScrollNext())
this.#toggleButtonsDisabledState(this.prevButtonTargets, !this.carousel.canScrollPrev())
}
// Button renders data-disabled next to disabled; keep both in step.
#toggleButtonsDisabledState(buttons, isDisabled) {
buttons.forEach((button) => {
button.disabled = isDisabled
button.toggleAttribute("data-disabled", isDisabled)
})
}
}
8
Update the Stimulus controllers manifest file
rake stimulus:manifest:update9
Install embla-carousel Javascript dependency
// with yarn
yarn add embla-carousel
// with npm
npm install embla-carousel
// with importmaps
bin/importmap pin embla-carousel
Components
| Component | Built using | Source |
|---|---|---|
Carousel | Phlex | |
CarouselContent | Phlex | |
CarouselDocs | Phlex | |
CarouselItem | Phlex | |
CarouselNext | Phlex | |
CarouselPrevious | Phlex | |
CarouselController | Stimulus JS |