{"record":{"id":"e577b61911011fab","repo":"shadcn-ui/ui","slug":"usecarousel-must-be-used-within-a-carousel-e577b6","errorCode":null,"errorMessage":"useCarousel must be used within a <Carousel />","messagePattern":"useCarousel must be used within a <Carousel />","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/v4/registry/new-york-v4/ui/carousel.tsx","lineNumber":39,"sourceCode":"  setApi?: (api: CarouselApi) => void\n}\n\ntype CarouselContextProps = {\n  carouselRef: ReturnType<typeof useEmblaCarousel>[0]\n  api: ReturnType<typeof useEmblaCarousel>[1]\n  scrollPrev: () => void\n  scrollNext: () => void\n  canScrollPrev: boolean\n  canScrollNext: boolean\n} & CarouselProps\n\nconst CarouselContext = React.createContext<CarouselContextProps | null>(null)\n\nfunction useCarousel() {\n  const context = React.useContext(CarouselContext)\n\n  if (!context) {\n    throw new Error(\"useCarousel must be used within a <Carousel />\")\n  }\n\n  return context\n}\n\nfunction Carousel({\n  orientation = \"horizontal\",\n  opts,\n  setApi,\n  plugins,\n  className,\n  children,\n  ...props\n}: React.ComponentProps<\"div\"> & CarouselProps) {\n  const [carouselRef, api] = useEmblaCarousel(\n    {\n      ...opts,\n      axis: orientation === \"horizontal\" ? \"x\" : \"y\",","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/shadcn-ui/ui/blob/efac5987074af84ece57c367c6dd83387b967022/apps/v4/registry/new-york-v4/ui/carousel.tsx#L21-L57","documentation":"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.","triggerScenarios":"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.","commonSituations":"Migrating an example away from the new-york-v4 style and losing the wrapper; rendering a carousel control in isolation in a test.","solutions":["Wrap the subtree in <Carousel>.","Move carousel sub-components back inside the <Carousel> tree.","Render isolated pieces inside a <Carousel> in stories/tests."],"exampleFix":"// before\n<CarouselPrevious />\n\n// after\n<Carousel>\n  <CarouselContent>\n    <CarouselItem>...</CarouselItem>\n  </CarouselContent>\n  <CarouselPrevious />\n</Carousel>","handlingStrategy":"validation","validationCode":"function useOptionalCarousel() {\n  return React.useContext(CarouselContext)\n}\nconst ctx = useOptionalCarousel()\nif (!ctx) return null","typeGuard":"function useHasCarousel(): boolean {\n  return React.useContext(CarouselContext) !== null\n}","tryCatchPattern":null,"preventionTips":["Always render new-york-v4 carousel sub-components inside <Carousel>.","Keep CarouselPrevious/CarouselNext colocated with CarouselContent.","Smoke-test carousel pieces within <Carousel>."],"tags":["react","context","carousel","new-york-v4"],"backgroundTag":null,"analyzedSha":"efac5987074af84ece57c367c6dd83387b967022","analyzedAt":"2026-08-12T05:00:50.218Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}