Glrk UI

Carousel

A simplified wrapper for Shadcn Carousel with data-driven slides and optional navigation controls

1
2
3
4
5
1
2
3
4
5
1
2
3
4
5

Installation

npx shadcn@latest add @glrk-ui/carousel

If you haven't set up the prerequisites yet, check out Prerequest section.

Copy and paste the following code into your project.

ui/carousel.tsx
'use client'

import * as React from 'react'
import useEmblaCarousel, { type UseEmblaCarouselType } from 'embla-carousel-react'
import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react'

import { cn } from '@/lib/utils'

import { Button } from '@/components/ui/button'

type CarouselApi = UseEmblaCarouselType[1]
type UseCarouselParameters = Parameters<typeof useEmblaCarousel>
type CarouselOptions = UseCarouselParameters[0]
type CarouselPlugin = UseCarouselParameters[1]

type CarouselProps = {
  opts?: CarouselOptions
  plugins?: CarouselPlugin
  orientation?: 'horizontal' | 'vertical'
  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',
    },
    plugins,
  )
  const [canScrollPrev, setCanScrollPrev] = React.useState(false)
  const [canScrollNext, setCanScrollNext] = React.useState(false)

  const onSelect = React.useCallback((api: CarouselApi) => {
    if (!api) return
    setCanScrollPrev(api.canScrollPrev())
    setCanScrollNext(api.canScrollNext())
  }, [])

  const scrollPrev = React.useCallback(() => {
    api?.scrollPrev()
  }, [api])

  const scrollNext = React.useCallback(() => {
    api?.scrollNext()
  }, [api])

  const handleKeyDown = React.useCallback(
    (event: React.KeyboardEvent<HTMLDivElement>) => {
      if (event.key === 'ArrowLeft') {
        event.preventDefault()
        scrollPrev()
      } else if (event.key === 'ArrowRight') {
        event.preventDefault()
        scrollNext()
      }
    },
    [scrollPrev, scrollNext],
  )

  React.useEffect(() => {
    if (!api || !setApi) return
    setApi(api)
  }, [api, setApi])

  React.useEffect(() => {
    if (!api) return
    onSelect(api)
    api.on('reInit', onSelect)
    api.on('select', onSelect)

    return () => {
      api?.off('select', onSelect)
    }
  }, [api, onSelect])

  return (
    <CarouselContext.Provider
      value={{
        carouselRef,
        api: api,
        opts,
        orientation: orientation || (opts?.axis === 'y' ? 'vertical' : 'horizontal'),
        scrollPrev,
        scrollNext,
        canScrollPrev,
        canScrollNext,
      }}
    >
      <div
        onKeyDownCapture={handleKeyDown}
        className={cn('relative', className)}
        role="region"
        aria-roledescription="carousel"
        data-slot="carousel"
        {...props}
      >
        {children}
      </div>
    </CarouselContext.Provider>
  )
}

function CarouselContent({ className, ...props }: React.ComponentProps<'div'>) {
  const { carouselRef, orientation } = useCarousel()

  return (
    <div ref={carouselRef} className="overflow-hidden" data-slot="carousel-content">
      <div
        className={cn('flex', orientation === 'horizontal' ? '-ml-4' : '-mt-4 flex-col', className)}
        {...props}
      />
    </div>
  )
}

function CarouselItem({ className, ...props }: React.ComponentProps<'div'>) {
  const { orientation } = useCarousel()

  return (
    <div
      role="group"
      aria-roledescription="slide"
      data-slot="carousel-item"
      className={cn(
        'min-w-0 shrink-0 grow-0 basis-full',
        orientation === 'horizontal' ? 'pl-4' : 'pt-4',
        className,
      )}
      {...props}
    />
  )
}

function CarouselPrevious({
  className,
  variant = 'outline',
  size = 'icon-sm',
  ...props
}: React.ComponentProps<typeof Button>) {
  const { orientation, scrollPrev, canScrollPrev } = useCarousel()

  return (
    <Button
      data-slot="carousel-previous"
      variant={variant}
      size={size}
      className={cn(
        'absolute touch-manipulation rounded-full',
        orientation === 'horizontal'
          ? 'top-1/2 -left-12 -translate-y-1/2'
          : '-top-12 left-1/2 -translate-x-1/2 rotate-90',
        className,
      )}
      disabled={!canScrollPrev}
      onClick={scrollPrev}
      {...props}
    >
      <ChevronLeftIcon />
      <span className="sr-only">Previous slide</span>
    </Button>
  )
}

function CarouselNext({
  className,
  variant = 'outline',
  size = 'icon-sm',
  ...props
}: React.ComponentProps<typeof Button>) {
  const { orientation, scrollNext, canScrollNext } = useCarousel()

  return (
    <Button
      data-slot="carousel-next"
      variant={variant}
      size={size}
      className={cn(
        'absolute touch-manipulation rounded-full',
        orientation === 'horizontal'
          ? 'top-1/2 -right-12 -translate-y-1/2'
          : '-bottom-12 left-1/2 -translate-x-1/2 rotate-90',
        className,
      )}
      disabled={!canScrollNext}
      onClick={scrollNext}
      {...props}
    >
      <ChevronRightIcon />
      <span className="sr-only">Next slide</span>
    </Button>
  )
}

type carouselItemT = {
  content: React.ReactNode
  itemCls?: string
}

type CarouselWrapperProps = {
  items: carouselItemT[]
  showControls?: boolean
  contentCls?: string
  itemCls?: string
  previousCls?: string
  nextCls?: string
}

function CarouselWrapper({
  items,
  showControls = true,
  contentCls,
  itemCls,
  previousCls,
  nextCls,
  ...props
}: React.ComponentProps<typeof Carousel> & CarouselWrapperProps) {
  return (
    <Carousel {...props}>
      <CarouselContent className={cn(contentCls)}>
        {items.map((item, index) => (
          <CarouselItem key={index} className={cn(itemCls, item.itemCls)}>
            {item.content}
          </CarouselItem>
        ))}
      </CarouselContent>

      {showControls && (
        <>
          <CarouselPrevious className={cn(previousCls)} />
          <CarouselNext className={cn(nextCls)} />
        </>
      )}
    </Carousel>
  )
}

export {
  type CarouselApi,
  type carouselItemT,
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselPrevious,
  CarouselNext,
  CarouselWrapper,
  useCarousel,
}

Usage

Basic

import { CarouselWrapper, type carouselItemT } from "@/components/ui/carousel";

const slides: carouselItemT[] = [
  { content: <div className="p-8 bg-muted rounded-lg">Slide 1</div> },
  { content: <div className="p-8 bg-muted rounded-lg">Slide 2</div> },
  { content: <div className="p-8 bg-muted rounded-lg">Slide 3</div> },
]

export function Basic() {
  return (
    <CarouselWrapper
      items={slides}
      className="w-full max-w-sm mx-auto"
    />
  )
}

Multi-slide per view

import { CarouselWrapper, type carouselItemT } from "@/components/ui/carousel";

export function MultiSlide() {
  const slides: carouselItemT[] = Array.from({ length: 6 }, (_, i) => ({
    content: (
      <div className="flex aspect-square items-center justify-center rounded-lg bg-muted text-xl font-semibold">
        {i + 1}
      </div>
    ),
  }))

  return (
    <CarouselWrapper
      items={slides}
      className="w-full max-w-sm mx-auto"
      opts={{ align: "start" }}
      itemCls="basis-1/3"
    />
  )
}

Vertical

import { CarouselWrapper, type carouselItemT } from "@/components/ui/carousel";

export function Vertical() {
  const slides: carouselItemT[] = [
    { content: <div className="flex h-32 items-center justify-center rounded-lg bg-muted">Slide 1</div> },
    { content: <div className="flex h-32 items-center justify-center rounded-lg bg-muted">Slide 2</div> },
    { content: <div className="flex h-32 items-center justify-center rounded-lg bg-muted">Slide 3</div> },
  ]

  return (
    <CarouselWrapper
      items={slides}
      orientation="vertical"
      opts={{ align: "start" }}
      className="w-full max-w-xs mx-auto"
    />
  )
}

Loop, no controls

import { CarouselWrapper, type carouselItemT } from "@/components/ui/carousel";

export function LoopNoControls() {
  const slides: carouselItemT[] = [
    { content: <img src="/slide-1.jpg" className="rounded-lg w-full" /> },
    { content: <img src="/slide-2.jpg" className="rounded-lg w-full" /> },
    { content: <img src="/slide-3.jpg" className="rounded-lg w-full" /> },
  ]

  return (
    <CarouselWrapper
      items={slides}
      opts={{ loop: true }}
      showControls={false}
      className="w-full max-w-sm mx-auto"
    />
  )
}

Controlled with API

import { useState } from "react"
import { CarouselWrapper, type CarouselApi, type carouselItemT } from "@/components/ui/carousel"

export function Controlled() {
  const [api, setApi] = useState<CarouselApi>()

  const slides: carouselItemT[] = Array.from({ length: 5 }, (_, i) => ({
    content: <div className="flex aspect-video items-center justify-center rounded-lg bg-muted text-lg">Slide {i + 1}</div>,
  }))

  return (
    <CarouselWrapper
      items={slides}
      setApi={setApi}
      className="w-full max-w-sm mx-auto"
    />
  )
}

Reference

carouselItemT

Prop

Type

CarouselWrapper

Prop

Type