组件

Carousel

Embla's smooth, swipeable scroller with paper furniture: hand-drawn arrows outside the slides (dashed when there is nowhere to go) and, if you want it, a tally under them: one stroke per slide, groups of five with the fifth struck across the other four, the current slide in blue felt. Horizontal or vertical, any number of slides per view, autoplay only if you plug it in.

安装

terminal
npx shadcn@latest add @wobko/carousel

第一次使用?先把 registry 加进 components.json。 如何安装

示例

Default

The shadcn demo: five cards and two arrows. Previous is dashed on the first slide; swipe or drag, click the arrows, or press Left and Right while focus is inside.

The tally, several at a time

CarouselDots keeps count like a tally: a stroke per slide, the fifth of each group struck across the four before it, the current one in blue felt (click any to go there). Seven slides, two per view on wide screens, and the API from setApi drives the caption.

Vertical

orientation="vertical": the slides scroll up and down, the arrows sit above and below with up and down arrows, and the keys are ArrowUp and ArrowDown. Give the track a fixed height and offset the gap with -mt on the content and pt on the items.

Photo stack (composed)

A real use: a trip's snapshots as taped-down polaroids. The line under the tally reads the current photo's date from the Embla API (the polaroid already carries its own caption); the tally counts them, and loops keep both arrows alive.

Sizes: several slides in view

A slide is as wide as its `basis-*` class: `basis-1/2` shows two, `basis-1/3` three. Breakpoint variants change it with the screen (here half from md, a third from lg), and `align: "start"` lines the first slide up with the left edge instead of centring it.

Spacing between slides

The gap is padding at the start of each item, pulled back by the same negative margin on the content, so the first slide still meets the edge. The default is `ps-4` with `-ms-4`; here it is `ps-1` with `-ms-1` for a tight row. Use the logical `ms`/`ps` (not `ml`/`pl`) so right-to-left pages work; vertical carousels use `pt` and `-mt`.

Autoplay (an Embla plugin)

Anything Embla understands goes in `plugins`; this small autoplay is written inline, so no extra package. It holds still while the pointer, focus or a finger is on the carousel, keeps a Pause through a resize, never starts for readers who asked for less motion, and has a real Pause button (WCAG 2.2.2).

API 参考

Carousel

The `role="region"` (`aria-roledescription="carousel"`, give it a name) that owns the Embla instance and the keys, plus a screen-reader status ("Slide 2 of 5").

属性类型默认值说明
optsEmblaOptionsType-Embla options: `loop`, `align`, `startIndex`, `dragFree`, `slidesToScroll`, `direction: "rtl"` ... (`axis` follows `orientation`).
pluginsEmblaPluginType[]-Embla plugins. Autoplay is not on by default: install `embla-carousel-autoplay` and pass it here if you really want it (and give people a way to stop it).
orientation"horizontal" | "vertical""horizontal"The axis the slides scroll along.
setApi(api: CarouselApi) => void-Receive the Embla API to read the current slide, listen to `select`, or scroll from outside.
seedstring | number-Pins the hand of the tally's strokes. Default: from useId().

无障碍

  • The APG carousel pattern: a labeled region (`aria-roledescription="carousel"`), slides that are groups (`aria-roledescription="slide"`; give each an `aria-label` such as "3 of 7" when the position matters), and previous / next buttons with names. A polite live region says "Slide 2 of 5" as it changes.
  • The arrow keys along the carousel's axis (Left and Right, mirrored in RTL; Up and Down when vertical) move it from anywhere inside it: on a button, a link or a slide. They are left alone while you are typing in a field (the caret's), when a widget inside a slide has already used the key (a radio group, tabs, a slider, a menu opened from a slide) and when a modifier is held (Alt+Left is the browser's Back). Your own `onKeyDown` on the Carousel runs first. Previous and next are ordinary buttons in the tab order.
  • The tally is a tablist with one tab stop (the current stroke); when the arrow keys move the carousel while focus is on it, focus goes along to the new current stroke. Strokes stay together in their group of five when the row wraps, and the tally clips its own drawings so they add no scroll area to the page. Each stroke is 24 by 32 px, is named "Go to slide n" and is marked with `aria-selected`; the current one is also bolder, taller and blue, so it does not rely on color alone.
  • Swipe and drag are Embla's. Nothing moves by itself. Reduced motion does not change Embla's scroll animation (configure `duration` in `opts` if you want it shorter).

源码

CLI 会复制进你项目的文件。

正在加载源码