react-carousel-latest/dist/index.d.ts

A headless, accessible, tree-shakeable React carousel with a compound-component API (and a backwards-compatible CardSlider preset).

import * as react from 'react';
export { C as CardSlider, a as CardSliderProps, b as CardSliderSlide, c as CardVariant, d as CubeSlide, e as CubeSlider, f as CubeSliderProps, I as ImageSlide, g as ImageSlider, h as ImageSliderProps, S as ShapeOption, i as SlicerSlide, j as SlicerSlider, k as SlicerSliderProps, C as default } from './CubeSlider-CjfZhUTb.js';

/**
 * Core carousel types.
 *
 * This module is intentionally free of React markup — it only describes the
 * data shapes that flow through the reducer and the public hook API. Keeping
 * types isolated lets the logic layer be reasoned about (and tested) without
 * pulling in any rendering concerns.
 */
type Orientation = "horizontal" | "vertical";
/** Resolved direction of a pointer drag. */
type DragDirection = "prev" | "next" | "none";
/** Details reported by {@link CarouselOptions.onDragEnd}. */
interface DragInfo {
    /** Signed pixel distance dragged (negative = toward the next slide). */
    delta: number;
    /** Which way the drag resolved, given the threshold. */
    direction: DragDirection;
}
/** Per-breakpoint overrides applied at or above a given min-width (px). */
interface ResponsiveOptions {
    slidesPerView?: number;
    slidesToScroll?: number;
}
/** Options accepted by {@link useCarousel} and the `<Carousel>` root. */
interface CarouselOptions {
    /** Total number of slides the carousel manages. */
    slidesCount: number;
    /** Slide shown on first render. Clamped into range. Default `0`. */
    initialIndex?: number;
    /** Wrap around past the first/last slide. Default `false`. */
    loop?: boolean;
    /** Start an autoplay timer. Default `false`. */
    autoplay?: boolean;
    /** Autoplay interval in milliseconds. Default `4000`. */
    autoplayInterval?: number;
    /** Slides advanced per prev/next call. Default `1`. */
    slidesToScroll?: number;
    /**
     * How many slides are visible at once. Default `1`. Sets `--rc-slide-size`
     * to `calc((100% - (n-1) * gap) / n)` and bounds navigation so the last
     * slide can't be scrolled past on its own.
     */
    slidesPerView?: number;
    /**
     * Responsive overrides keyed by min-width in px, e.g.
     * `{ 768: { slidesPerView: 2 }, 1024: { slidesPerView: 4 } }`.
     * The largest matching breakpoint wins.
     */
    breakpoints?: Record<number, ResponsiveOptions>;
    /** Layout axis. Default `"horizontal"`. */
    orientation?: Orientation;
    /** Fired whenever the active slide changes (programmatic or gesture). */
    onIndexChange?: (index: number) => void;
    /** Fired after a slide transition settles (or immediately when motion is off). */
    onSettle?: (index: number) => void;
    /** Fired when a pointer swipe begins. */
    onSwipeStart?: () => void;
    /** Fired when a pointer swipe ends, with the resolved drag info. */
    onSwipeEnd?: (info: DragInfo) => void;
}
/** The serialisable state owned by the reducer. */
interface CarouselState {
    activeIndex: number;
    slidesCount: number;
    slidesPerView: number;
    isPlaying: boolean;
}
/** Actions understood by {@link carouselReducer}. */
type CarouselAction = {
    type: "NEXT";
    step: number;
    loop: boolean;
} | {
    type: "PREV";
    step: number;
    loop: boolean;
} | {
    type: "GO_TO";
    index: number;
} | {
    type: "SET_COUNT";
    slidesCount: number;
} | {
    type: "SET_SLIDES_PER_VIEW";
    slidesPerView: number;
} | {
    type: "SET_PLAYING";
    isPlaying: boolean;
};
/**
 * The public surface returned by {@link useCarousel}. Components consume this
 * through context; advanced users can consume it directly to build bespoke UI.
 */
interface CarouselApi {
    /** Index of the currently active slide. */
    activeIndex: number;
    /** Total slide count. */
    slidesCount: number;
    /** Whether autoplay is currently running. */
    isPlaying: boolean;
    /** True when {@link prev} would move (always true when `loop`). */
    canPrev: boolean;
    /** True when {@link next} would move (always true when `loop`). */
    canNext: boolean;
    /** Resolved orientation. */
    orientation: Orientation;
    /** Resolved slides-per-view (after breakpoints). Default `1`. */
    slidesPerView: number;
    next: () => void;
    prev: () => void;
    goTo: (index: number) => void;
    play: () => void;
    pause: () => void;
    /** Ref for the moving track element (transform target + swipe surface). */
    trackRef: React.RefObject<HTMLDivElement | null>;
    /** Ref for the outer region element (keyboard + autoplay-pause surface). */
    rootRef: React.RefObject<HTMLDivElement | null>;
}
/**
 * Imperative handle exposed via a `ref` on `<Carousel>` — lets a parent drive
 * navigation without consuming the headless hook directly.
 */
interface CarouselHandle {
    activeIndex: number;
    canPrev: boolean;
    canNext: boolean;
    next: () => void;
    prev: () => void;
    goTo: (index: number) => void;
    play: () => void;
    pause: () => void;
}

interface CarouselProps extends CarouselOptions, Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
    /** Accessible name for the carousel region. Default `"Carousel"`. */
    label?: string;
    children: React.ReactNode;
}

interface TrackProps extends React.HTMLAttributes<HTMLDivElement> {
    children: React.ReactNode;
}
/**
 * The clipping viewport plus the moving track. The track is translated by
 * `--rc-active-index` (set here) combined with the live `--rc-drag` offset that
 * {@link useSwipe} writes during a gesture — all resolved in CSS.
 */
declare function Track({ children, className, style, ...rest }: TrackProps): react.JSX.Element;

interface SlideProps extends React.HTMLAttributes<HTMLDivElement> {
    /**
     * Zero-based position of this slide. Required so the slide can label itself
     * for assistive tech and report whether it is the active one.
     */
    index: number;
    children: React.ReactNode;
}
/** A single slide. Sizing is governed by the `--rc-slide-size` CSS variable. */
declare function Slide({ index, children, className, ...rest }: SlideProps): react.JSX.Element;

type ButtonDirection = "prev" | "next" | "first" | "last";
interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> {
    /** Navigation action this button controls. */
    dir: ButtonDirection;
}
/**
 * Navigation control. `prev`/`next` step one (overlaying the track edges);
 * `first`/`last` jump to the ends. Disables itself at the bounds when the
 * carousel is not looping, and falls back to a built-in icon + ARIA label.
 */
declare function Button({ dir, className, children, disabled, "aria-label": ariaLabel, ...rest }: ButtonProps): react.JSX.Element;

interface DotsProps extends React.HTMLAttributes<HTMLDivElement> {
    /** Accessible label for a given dot. Default `"Go to slide N"`. */
    dotLabel?: (index: number) => string;
}
/** Clickable pagination indicators, one per slide. */
declare function Dots({ className, dotLabel, ...rest }: DotsProps): react.JSX.Element;

interface PlayPauseProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> {
}
/**
 * Toggles autoplay. Reflects state via `aria-pressed` and swaps the label
 * between "Play"/"Pause".
 */
declare function PlayPause({ className, children, "aria-label": ariaLabel, ...rest }: PlayPauseProps): react.JSX.Element;

/**
 * The compound carousel. Use the namespaced parts for the common case:
 *
 * ```tsx
 * <Carousel slidesCount={items.length} loop autoplay>
 *   <Carousel.Button dir="prev" />
 *   <Carousel.Track>
 *     {items.map((item, i) => (
 *       <Carousel.Slide key={item.id} index={i}>{item.content}</Carousel.Slide>
 *     ))}
 *   </Carousel.Track>
 *   <Carousel.Button dir="next" />
 *   <div className="rc-controls">
 *     <Carousel.Button dir="first" />
 *     <Carousel.PlayPause />
 *     <Carousel.Button dir="last" />
 *   </div>
 *   <Carousel.Dots />
 * </Carousel>
 * ```
 *
 * The parts are also exported individually for tree-shaking or custom layouts.
 */
declare const Carousel: react.ForwardRefExoticComponent<CarouselProps & react.RefAttributes<CarouselHandle>> & {
    Track: typeof Track;
    Slide: typeof Slide;
    Button: typeof Button;
    Dots: typeof Dots;
    PlayPause: typeof PlayPause;
};

/**
 * The headless heart of the library: owns navigation state and composes the
 * keyboard, swipe, and autoplay behaviours into a single {@link CarouselApi}.
 *
 * Use it directly to build a fully custom UI, or let `<Carousel>` call it and
 * expose the result through context to the compound components.
 */
declare function useCarousel(options: CarouselOptions): CarouselApi;

export { Button, type ButtonDirection, type ButtonProps, Carousel, type CarouselAction, type CarouselApi, type CarouselHandle, type CarouselOptions, type CarouselProps, type CarouselState, Dots, type DotsProps, type DragDirection, type DragInfo, type Orientation, PlayPause, type PlayPauseProps, type ResponsiveOptions, Slide, type SlideProps, Track, type TrackProps, useCarousel };