shadcn-ui/ui · error · Error

useCarousel must be used within a <Carousel />

Error message

useCarousel must be used within a <Carousel />

What it means

Same guard as the bases/radix carousel: useCarousel reads CarouselContext, which only <Carousel> populates. This copy lives under registry/new-york-v4 (a legacy source style) so the trigger and fix are identical to the radix carousel hook.

Source

Thrown at apps/v4/registry/new-york-v4/ui/carousel.tsx:39

  setApi?: (api: CarouselApi) => void
}

type CarouselContextProps = {
  carouselRef: ReturnType<typeof useEmblaCarousel>[0]
  api: ReturnType<typeof useEmblaCarousel>[1]
  scrollPrev: () => void
  scrollNext: () => void
  canScrollPrev: boolean
  canScrollNext: boolean
} & CarouselProps

const CarouselContext = React.createContext<CarouselContextProps | null>(null)

function useCarousel() {
  const context = React.useContext(CarouselContext)

  if (!context) {
    throw new Error("useCarousel must be used within a <Carousel />")
  }

  return context
}

function Carousel({
  orientation = "horizontal",
  opts,
  setApi,
  plugins,
  className,
  children,
  ...props
}: React.ComponentProps<"div"> & CarouselProps) {
  const [carouselRef, api] = useEmblaCarousel(
    {
      ...opts,
      axis: orientation === "horizontal" ? "x" : "y",

View on GitHub (pinned to efac598707)

Solutions

1. Wrap the subtree in <Carousel>.
2. Move carousel sub-components back inside the <Carousel> tree.
3. Render isolated pieces inside a <Carousel> in stories/tests.

Example fix

// before
<CarouselPrevious />

// after
<Carousel>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
</Carousel>

function useOptionalCarousel() {
  return React.useContext(CarouselContext)
}
const ctx = useOptionalCarousel()
if (!ctx) return null

function useHasCarousel(): boolean {
  return React.useContext(CarouselContext) !== null
}

When it happens

Trigger: Using new-york-v4 carousel sub-components (CarouselItem/CarouselPrevious/CarouselNext) without a <Carousel> ancestor; importing useCarousel from the new-york-v4 registry path in a standalone component.

Common situations: Migrating an example away from the new-york-v4 style and losing the wrapper; rendering a carousel control in isolation in a test.

Related errors

• useCarousel must be used within a <Carousel />
• useCarousel must be used within a <Carousel />
• useCarousel must be used within a <Carousel />
• useChart must be used within a <ChartContainer />
• useSidebar must be used within a SidebarProvider.

AI-assisted analysis of shadcn-ui/ui@efac598707 (2026-08-12). Data as JSON: /api/errors/e577b61911011fab. Report an issue: GitHub.