Carousel

01Install

02Configure

03Write

04Publish

󰯠󰯮

Import

import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselControls,
  CarouselPrevious,
  CarouselNext,
  CarouselIndicators,
} from "@pelagornis/page/components";

Example

The preview above renders this file. Copy it into src/components/ to start from it.

src/components/CarouselExample.tsx

import {
  Box,
  Carousel,
  CarouselContent,
  CarouselControls,
  CarouselIndicators,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
  Stack,
  Text,
} from "@pelagornis/page/components";

const slides = [
  { eyebrow: "01", title: "Install" },
  { eyebrow: "02", title: "Configure" },
  { eyebrow: "03", title: "Write" },
  { eyebrow: "04", title: "Publish" },
];

export default function CarouselDemo() {
  return (
    <Carousel loop className="w-full">
      <CarouselContent>
        {slides.map((slide) => (
          <CarouselItem key={slide.title}>
            <Box
              padding="sizeXLarge"
              background="backgroundBrand"
              className="flex min-h-refineui-foundation-size-2000 flex-col justify-end"
            >
              <Stack gap="sizeXSmall">
                <Text variant="captionMd" className="m-0 text-refineui-alias-foreground-on-brand">
                  {slide.eyebrow}
                </Text>
                <Text as="strong" variant="titleMd" className="text-refineui-alias-foreground-on-brand">
                  {slide.title}
                </Text>
              </Stack>
            </Box>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselControls>
        <CarouselPrevious />
        <CarouselIndicators />
        <CarouselNext />
      </CarouselControls>
    </Carousel>
  );
}

Use in MDX

Carousel is composed from parts that share React state. Children written in MDX are rendered as separate islands, so the parts can’t reach each other. Put the composition in a .tsx file, like the example above, and import that file instead.

src/content/docs/example.mdx

---
title: Example
---

import CarouselExample from "../../components/CarouselExample";

<CarouselExample client:load />

client:load hydrates the island on page load. Use client:visible for content far down the page.

Use in Markdoc

Markdoc tags render Astro components, and this one needs client state. Wrap the example in an .astro file that hydrates it, then register that file as a tag.

src/components/markdoc/CarouselExample.astro

---
import CarouselExample from "../CarouselExample";
---

<CarouselExample client:load />

markdoc.config.mjs

import { component, defineMarkdocConfig } from "@astrojs/markdoc/config";
import starlightMarkdoc from "@astrojs/starlight-markdoc";
import pageMarkdoc from "@pelagornis/page/markdoc";

export default defineMarkdocConfig({
  extends: [starlightMarkdoc(), pageMarkdoc()],
  tags: {
    "carousel-example": {
      render: component("./src/components/markdoc/CarouselExample.astro"),
      selfClosing: true,
    },
  },
});

src/content/docs/example.mdoc

{% carousel-example /%}

Anatomy

Parts of the component and the data-refineui role each one renders.

Part	Role
root	carousel
controls	carousel-controls
indicator	carousel-indicator
indicator_hits	carousel-indicator-hits
indicator_thumb	carousel-indicator-thumb
indicators	carousel-indicators
item	carousel-item
nav	carousel-nav
track	carousel-track
viewport	carousel-viewport

States

States the component styles. Component states are exposed as data attributes.

Kind	States
Pseudo	focus-visible

Keyboard

Keys the component handles when it has focus.

Key	Action
ArrowRight	next-trigger
ArrowLeft	previous-trigger
Home	first-trigger
End	last-trigger

Reference

• RefineUI · Carousel for design guidance and token detail.
• Use in MDX and Use in Markdoc for the general rules.