feat(carousel): indicator and progress text

Author: segunadebayo

packages/react/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+### Added
+
+- **Carousel**:
+  - Added `Carousel.AutoplayIndicator` component for conditionally rendering content based on autoplay state
+  - Added `Carousel.ProgressText` component for displaying current page progress (e.g., "1 / 5")
+
 ## [5.27.1] - 2025-11-02
 
 ### Fixed

packages/react/src/components/carousel/carousel-autoplay-indicator.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react'
+import { useCarouselContext } from './use-carousel-context'
+
+export interface CarouselAutoplayIndicatorBaseProps {
+  /**
+   * The content to render when autoplay is paused.
+   */
+  paused: ReactNode
+  /**
+   * The content to render when autoplay is playing.
+   */
+  playing: ReactNode
+}
+export interface CarouselAutoplayIndicatorProps extends CarouselAutoplayIndicatorBaseProps {}
+
+export const CarouselAutoplayIndicator = (props: CarouselAutoplayIndicatorProps) => {
+  const carousel = useCarouselContext()
+  return <>{carousel.isPlaying ? props.paused : props.playing}</>
+}
+
+CarouselAutoplayIndicator.displayName = 'CarouselAutoplayIndicator'

packages/react/src/components/carousel/carousel-progress-text.tsx

@@ -0,0 +1,27 @@
+import { forwardRef, useMemo } from 'react'
+import { type HTMLProps, type PolymorphicProps, ark } from '../factory'
+import { carouselAnatomy } from './carousel.anatomy'
+import { useCarouselContext } from './use-carousel-context'
+
+const parts = carouselAnatomy.build()
+
+export interface CarouselProgressTextBaseProps extends PolymorphicProps {}
+export interface CarouselProgressTextProps extends HTMLProps<'span'>, CarouselProgressTextBaseProps {}
+
+export const CarouselProgressText = forwardRef<HTMLSpanElement, CarouselProgressTextProps>((props, ref) => {
+  const carousel = useCarouselContext()
+
+  const progressText = useMemo(() => {
+    const currentPage = carousel.page + 1
+    const totalPages = carousel.pageSnapPoints.length
+    return `${currentPage} / ${totalPages}`
+  }, [carousel.page, carousel.pageSnapPoints.length])
+
+  return (
+    <ark.span ref={ref} {...parts.progressText.attrs} {...props}>
+      {props.children || progressText}
+    </ark.span>
+  )
+})
+
+CarouselProgressText.displayName = 'CarouselProgressText'

packages/react/src/components/carousel/carousel.anatomy.ts

@@ -1 +1,3 @@
-export { anatomy as carouselAnatomy } from '@zag-js/carousel'
+import { anatomy } from '@zag-js/carousel'
+
+export const carouselAnatomy = anatomy.extendWith('progressText')

packages/react/src/components/carousel/carousel.ts

@@ -1,4 +1,14 @@
 export type { AutoplayStatusDetails, DragStatusDetails, PageChangeDetails } from '@zag-js/carousel'
+export {
+  CarouselAutoplayIndicator as AutoplayIndicator,
+  type CarouselAutoplayIndicatorBaseProps as AutoplayIndicatorBaseProps,
+  type CarouselAutoplayIndicatorProps as AutoplayIndicatorProps,
+} from './carousel-autoplay-indicator'
+export {
+  CarouselProgressText as ProgressText,
+  type CarouselProgressTextBaseProps as ProgressTextBaseProps,
+  type CarouselProgressTextProps as ProgressTextProps,
+} from './carousel-progress-text'
 export {
   CarouselAutoplayTrigger as AutoplayTrigger,
   type CarouselAutoplayTriggerBaseProps as AutoplayTriggerBaseProps,

packages/react/src/components/carousel/examples/autoplay.tsx

@@ -7,8 +7,9 @@ export const Autoplay = () => {
     <Carousel.Root slideCount={images.length} autoplay loop>
       <Carousel.Control>
         <Carousel.AutoplayTrigger>
-          <Carousel.Context>{({ isPlaying }) => (isPlaying ? 'Pause' : 'Play')}</Carousel.Context>
+          <Carousel.AutoplayIndicator paused="Pause" playing="Play" />
         </Carousel.AutoplayTrigger>
+        <Carousel.ProgressText />
       </Carousel.Control>
       <Carousel.IndicatorGroup>
         {images.map((_, index) => (

packages/react/src/components/carousel/index.ts

@@ -3,6 +3,16 @@ export type {
   DragStatusDetails as CarouselDragStatusDetails,
   PageChangeDetails as CarouselPageChangeDetails,
 } from '@zag-js/carousel'
+export {
+  CarouselAutoplayIndicator,
+  type CarouselAutoplayIndicatorBaseProps,
+  type CarouselAutoplayIndicatorProps,
+} from './carousel-autoplay-indicator'
+export {
+  CarouselProgressText,
+  type CarouselProgressTextBaseProps,
+  type CarouselProgressTextProps,
+} from './carousel-progress-text'
 export {
   CarouselAutoplayTrigger,
   type CarouselAutoplayTriggerBaseProps,

packages/solid/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+### Added
+
+- **Carousel**:
+  - Added `Carousel.AutoplayIndicator` component for conditionally rendering content based on autoplay state
+  - Added `Carousel.ProgressText` component for displaying current page progress (e.g., "1 / 5")
+
 ## [5.27.1] - 2025-11-02
 
 ### Fixed

packages/solid/src/components/carousel/carousel-autoplay-indicator.tsx

@@ -0,0 +1,23 @@
+import { Show, type JSX } from 'solid-js'
+import { useCarouselContext } from './use-carousel-context'
+
+export interface CarouselAutoplayIndicatorBaseProps {
+  /**
+   * The content to render when autoplay is paused.
+   */
+  paused: JSX.Element
+  /**
+   * The content to render when autoplay is playing.
+   */
+  playing: JSX.Element
+}
+export interface CarouselAutoplayIndicatorProps extends CarouselAutoplayIndicatorBaseProps {}
+
+export const CarouselAutoplayIndicator = (props: CarouselAutoplayIndicatorProps) => {
+  const api = useCarouselContext()
+  return (
+    <Show when={api().isPlaying} fallback={props.playing}>
+      {props.paused}
+    </Show>
+  )
+}

packages/solid/src/components/carousel/carousel-progress-text.tsx

@@ -0,0 +1,25 @@
+import { createMemo } from 'solid-js'
+import { type HTMLProps, type PolymorphicProps, ark } from '../factory'
+import { carouselAnatomy } from './carousel.anatomy'
+import { useCarouselContext } from './use-carousel-context'
+
+const parts = carouselAnatomy.build()
+
+export interface CarouselProgressTextBaseProps extends PolymorphicProps<'span'> {}
+export interface CarouselProgressTextProps extends HTMLProps<'span'>, CarouselProgressTextBaseProps {}
+
+export const CarouselProgressText = (props: CarouselProgressTextProps) => {
+  const api = useCarouselContext()
+
+  const progressText = createMemo(() => {
+    const currentPage = api().page + 1
+    const totalPages = api().pageSnapPoints.length
+    return `${currentPage} / ${totalPages}`
+  })
+
+  return (
+    <ark.span {...parts.progressText.attrs} {...props}>
+      {props.children || progressText()}
+    </ark.span>
+  )
+}