Carousel

API

Generated CoreAI prop summaries, not replacement type declarations. Most native DOM/event and ARIA props are omitted. ? means optional; JSDoc shows defaults, deprecations, and conditional requirements. Defaults assume the standard CoreAI provider.

Carousel API

Carousel is the context wrapper and container for all carousel content/controls, it has no direct style or slot opinions.

Carousel also provides API interfaces for callbacks that will occur on navigation events.

interface CarouselProps {
  /**
   * The value of the currently active page.
   */
  activeIndex?: number;

  /**
   * The alignment of the carousel.
   */
  align?: "center" | "start" | "end";

  /**
   * Localizes the string used to announce carousel page changes
   * Defaults to: undefined
   */
  announcement?: CarouselAnnouncerFunction;

  /**
   * Sets visual treatment for the Carousel container.
   *
   * `flat`
   * Retains the minimal styling used by default prior to introducing appearance-based styles.
   *
   * `elevated`
   * Applies rounded corners, background, and shadow tokens so the Carousel is presented as a surfaced container.
   * @default 'flat'
   */
  appearance?: "flat" | "elevated";

  as?: "div";

  /**
   * Choose a delay between autoplay transitions in milliseconds.
   * Only active if Autoplay is enabled via CarouselAutoplayButton
   *
   * Defaults: 4000
   */
  autoplayInterval?: number;

  children?: any;

  /**
   * Circular enables the carousel to loop back around on navigation past trailing index.
   */
  circular?: boolean;

  className?: string;

  /**
   * The initial page to display in uncontrolled mode.
   */
  defaultActiveIndex?: number;

  /**
   * Enables drag to scroll on carousel items.
   * Defaults to: False
   */
  draggable?: Booleanish;

  /**
   * Controls the number of carousel cards per navigation element, will default to 'auto'
   * Recommended to set to '1' when using full page carousel cards.
   */
  groupSize?: number | "auto";

  /**
   * Sets motion type as either 'slide' or 'fade'
   * Defaults: 'slide'
   *
   * Users can also pass 'slide' & duration via CarouselMotion object to control carousel speed.
   * Drag interactions are not affected because duration is then determined by the drag force.
   *
   * Note: Duration is not in milliseconds because Carousel uses an
   * attraction physics simulation when scrolling instead of easings.
   * Only values between 20-60 are recommended, 25 is the default.
   */
  motion?: CarouselMotion;

  /**
   * Callback to notify a page change.
   */
  onActiveIndexChange?: EventHandler<CarouselIndexChangeData>;

  ref?: Ref<HTMLDivElement>;

  style?: CSSProperties;

  /**
   * Adds whitespace to start/end so that 'align' prop is always respected for current index
   * Defaults to: False
   */
  whitespace?: boolean;
}

CarouselAutoplayButton API

If the Carousel is on auto-play, the user may opt into pausing the auto-play feature via the CarouselAutoplayButton which must be present for auto-play to be enabled.

If CarouselAutoplayButton is present, auto-play will default to true on mount.

interface CarouselAutoplayButtonProps {
  /**
   * A button can have its content and borders styled for greater emphasis or to be subtle.
   * - 'secondary' (default): Gives emphasis to the button in such a way that it indicates a secondary action.
   * - 'primary': Emphasizes the button as a primary action.
   * - 'outline': Removes background styling.
   * - 'subtle': Minimizes emphasis to blend into the background until hovered or focused.
   * - 'transparent': Removes background and border styling.
   * @default 'secondary'
   */
  appearance?: "outline" | "subtle" | "secondary" | "primary" | "transparent";

  as?: "a" | "button";

  /**
   * Defines the controlled checked state of the `ToggleButton`.
   * If passed, `ToggleButton` ignores the `defaultChecked` property.
   * This should only be used if the checked state is to be controlled at a higher level and there is a plan to pass the
   * correct value based on handling `onClick` events and re-rendering.
   * @default false
   */
  checked?: boolean;

  children?: any;

  className?: string;

  /**
   * Defines whether the `ToggleButton` is initially in a checked state or not when rendered.
   * @default false
   */
  defaultChecked?: boolean;

  /**
   * A button can show that it cannot be interacted with.
   * @default false
   */
  disabled?: boolean;

  /**
   * When set, allows the button to be focusable even when it has been disabled.
   * This is used in scenarios where it is important to keep a consistent tab order
   * for screen reader and keyboard users. The primary example of this
   * pattern is when the disabled button is in a menu or a commandbar and is seldom used for standalone buttons.
   * When set, allows the button to be focusable even when it has been disabled. This is used in scenarios where it
   * is important to keep a consistent tab order for screen reader and keyboard users. The primary example of this
   * pattern is when the disabled button is in a menu or a commandbar and is seldom used for standalone buttons.
   * @default false
   * false
   */
  disabledFocusable?: boolean;

  /**
   * Icon that renders either before or after the `children` as specified by the `iconPosition` prop.
   */
  icon?: WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * A button can format its icon to appear before or after its content.
   * @default 'before'
   */
  iconPosition?: "before" | "after";

  /**
   * Defines whether the `ToggleButton` should use the alternate selected styles that have adequate contrast with the rest style
   * @default false
   */
  isAccessible?: boolean;

  /**
   * Callback that informs the user when internal autoplay value has changed
   */
  onCheckedChange?: EventHandler<CarouselAutoplayChangeData>;

  ref?: Ref<HTMLAnchorElement | HTMLButtonElement>;

  /**
   * A button can be rounded, circular, or square.
   * @default 'rounded'
   */
  shape?: "circular" | "rounded" | "square";

  /**
   * A button supports different sizes.
   * @default 'medium'
   */
  size?: "small" | "medium" | "large";

  style?: CSSProperties;
}

CarouselButton API

A default navigation button that will set value to the next/previous page, driven by it's type 'next' or 'previous'.

interface CarouselButtonProps {
  /**
   * A button can have its content and borders styled for greater emphasis or to be subtle.
   * - 'secondary' (default): Gives emphasis to the button in such a way that it indicates a secondary action.
   * - 'primary': Emphasizes the button as a primary action.
   * - 'outline': Removes background styling.
   * - 'subtle': Minimizes emphasis to blend into the background until hovered or focused.
   * - 'transparent': Removes background and border styling.
   * @default 'secondary'
   */
  appearance?: "outline" | "subtle" | "secondary" | "primary" | "transparent";

  as?: "a" | "button";

  children?: any;

  className?: string;

  /**
   * A button can show that it cannot be interacted with.
   * @default false
   */
  disabled?: boolean;

  /**
   * When set, allows the button to be focusable even when it has been disabled.
   * This is used in scenarios where it is important to keep a consistent tab order
   * for screen reader and keyboard users. The primary example of this
   * pattern is when the disabled button is in a menu or a commandbar and is seldom used for standalone buttons.
   * When set, allows the button to be focusable even when it has been disabled. This is used in scenarios where it
   * is important to keep a consistent tab order for screen reader and keyboard users. The primary example of this
   * pattern is when the disabled button is in a menu or a commandbar and is seldom used for standalone buttons.
   * @default false
   * false
   */
  disabledFocusable?: boolean;

  /**
   * Icon that renders either before or after the `children` as specified by the `iconPosition` prop.
   */
  icon?: WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * A button can format its icon to appear before or after its content.
   * @default 'before'
   */
  iconPosition?: "before" | "after";

  /**
   * Dictates whether button will be of type go next or go previous
   * Default: 'next'
   */
  navType?: "next" | "prev";

  ref?: Ref<HTMLAnchorElement | HTMLButtonElement>;

  /**
   * A button can be rounded, circular, or square.
   * @default 'rounded'
   */
  shape?: "circular" | "rounded" | "square";

  /**
   * A button supports different sizes.
   * @default 'medium'
   */
  size?: "small" | "medium" | "large";

  style?: CSSProperties;
}

CarouselCard API

The defining wrapper of a carousel's indexed content, they will take up the full viewport of CarouselSlider or div wrapper, users may place multiple items within this Card if desired, with consideration of viewport width.

Clickable actions within the content area are available via mouse and tab as expected, non-active card content will be set to inert until moved to active card.

interface CarouselCardProps {
  as?: "div";

  /**
   * Sets the card styling to be responsive based on content.
   */
  autoSize?: boolean;

  children?: any;

  className?: string;

  ref?: Ref<HTMLDivElement>;

  style?: CSSProperties;
}

CarouselNav API

Used to jump to a card based on index, using arrow navigation via Tabster.

The children of this component will be wrapped in a context to provide the appropriate value based on their index position.

interface CarouselNavProps {
  /**
   * Enables an alternate brand style when set to 'brand'
   */
  appearance?: "brand";

  as?: "div";

  children: NavButtonRenderFunction;

  className?: string;

  ref?: Ref<HTMLDivElement>;

  style?: CSSProperties;

  /**
   * The total number of slides available.
   * Users may override if using the component without a Carousel wrapper or implementing custom functionality.
   */
  totalSlides?: number;
}

CarouselNavButton API

The child element of CarouselNav, a singular button that will set the carousels active value on click.

interface CarouselNavButtonProps {
  as?: "a" | "button" | "div";

  children?: any;

  className?: string;

  disabled?: boolean;

  /**
   * When set, allows the button to be focusable even when it has been disabled.
   * This is used in scenarios where it is important to keep a consistent tab order
   * for screen reader and keyboard users. The primary example of this
   * pattern is when the disabled button is in a menu or a commandbar and is seldom used for standalone buttons.
   * @default false
   */
  disabledFocusable?: boolean;

  ref?: Ref<HTMLAnchorElement | HTMLButtonElement | HTMLDivElement>;

  style?: CSSProperties;
}

CarouselNavContainer API

CarouselNavContainer component - This container will provide multiple valid layout options for the underlying carousel controls

interface CarouselNavContainerProps {
  as?: "div";

  autoplay?: WithSlotShorthandValue<(Omit<ButtonSlots, "root"> & Omit<{ as?: "button"; } & Omit<Omit<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & { ref?: ((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { appearance?: "outline" | "subtle" | "secondary" | "primary" | "transparent" | undefined; disabledFocusable?: boolean | undefined; disabled?: boolean | undefined; iconPosition?: "before" | "after" | undefined; shape?: "circular" | "rounded" | "square" | undefined; size?: ButtonSize | undefined; } & { defaultChecked?: boolean | undefined; checked?: boolean | undefined; isAccessible?: boolean | undefined; } & Omit<CarouselAutoplayButtonSlots, "root"> & { onCheckedChange?: EventHandler<CarouselAutoplayChangeData> | undefined; } & RefAttributes<HTMLAnchorElement | HTMLButtonElement>) | (Omit<ButtonSlots, "root"> & Omit<{ as: "a"; } & Omit<Omit<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, "ref"> & { ref?: ((instance: HTMLAnchorElement | null) => void) | RefObject<HTMLAnchorElement> | null | undefined; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { appearance?: "outline" | "subtle" | "secondary" | "primary" | "transparent" | undefined; disabledFocusable?: boolean | undefined; disabled?: boolean | undefined; iconPosition?: "before" | "after" | undefined; shape?: "circular" | "rounded" | "square" | undefined; size?: ButtonSize | undefined; } & { defaultChecked?: boolean | undefined; checked?: boolean | undefined; isAccessible?: boolean | undefined; } & Omit<CarouselAutoplayButtonSlots, "root"> & { onCheckedChange?: EventHandler<CarouselAutoplayChangeData> | undefined; } & RefAttributes<HTMLAnchorElement | HTMLButtonElement>)> | null | undefined;

  autoplayTooltip?: WithSlotShorthandValue<TooltipProps> | null;

  children?: any;

  className?: string;

  /**
   * Default: 'inline'
   * Defines the nav container layout:
   *
   * 'inline' - Default controls inline with carousel view
   *
   *  inline-wide - Similar to inline but places nav buttons on far left/right
   *
   * 'overlay' - Controls overlaid on bottom of carousel viewport,
   *
   * 'overlay-wide' - Controls overlaid on bottom of carousel viewport with prev+autoplay/next buttons on far side
   *
   * 'overlay-expanded' - Controls overlaid on bottom of carousel viewport, with prev/next buttons on sides vertically centered
   */
  layout?: "inline" | "inline-wide" | "overlay" | "overlay-wide" | "overlay-expanded";

  next?: WithSlotShorthandValue<(Partial<Omit<ButtonSlots, "root"> & Omit<{ as?: "button"; } & Omit<Omit<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & { ref?: ((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { appearance?: "outline" | "subtle" | "secondary" | "primary" | "transparent" | undefined; disabledFocusable?: boolean | undefined; disabled?: boolean | undefined; iconPosition?: "before" | "after" | undefined; shape?: "circular" | "rounded" | "square" | undefined; size?: ButtonSize | undefined; }> & Omit<CarouselButtonSlots, "root"> & Omit<{ as?: "button" | undefined; } & Omit<Omit<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & { ref?: ((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null | undefined; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { navType?: "next" | "prev" | undefined; }) | (Partial<Omit<ButtonSlots, "root"> & Omit<{ as: "a"; } & Omit<Omit<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, "ref"> & { ref?: ((instance: HTMLAnchorElement | null) => void) | RefObject<HTMLAnchorElement> | null | undefined; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { appearance?: "outline" | "subtle" | "secondary" | "primary" | "transparent" | undefined; disabledFocusable?: boolean | undefined; disabled?: boolean | undefined; iconPosition?: "before" | "after" | undefined; shape?: "circular" | "rounded" | "square" | undefined; size?: ButtonSize | undefined; }> & Omit<CarouselButtonSlots, "root"> & Omit<{ as?: "button" | undefined; } & Omit<Omit<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & { ref?: ((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null | undefined; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { navType?: "next" | "prev" | undefined; }) | (Partial<Omit<ButtonSlots, "root"> & Omit<{ as: "a"; } & Omit<Omit<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, "ref"> & { ref?: ((instance: HTMLAnchorElement | null) => void) | RefObject<HTMLAnchorElement> | null | undefined; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { appearance?: "outline" | "subtle" | "secondary" | "primary" | "transparent" | undefined; disabledFocusable?: boolean | undefined; disabled?: boolean | undefined; iconPosition?: "before" | "after" | undefined; shape?: "circular" | "rounded" | "square" | undefined; size?: ButtonSize | undefined; }> & Omit<CarouselButtonSlots, "root"> & Omit<{ as: "a"; } & Omit<Omit<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, "ref"> & { ref?: ((instance: HTMLAnchorElement | null) => void) | RefObject<HTMLAnchorElement> | null | undefined; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { navType?: "next" | "prev" | undefined; })> | null | undefined;

  nextTooltip?: WithSlotShorthandValue<TooltipProps> | null;

  prev?: WithSlotShorthandValue<(Partial<Omit<ButtonSlots, "root"> & Omit<{ as?: "button"; } & Omit<Omit<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & { ref?: ((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { appearance?: "outline" | "subtle" | "secondary" | "primary" | "transparent" | undefined; disabledFocusable?: boolean | undefined; disabled?: boolean | undefined; iconPosition?: "before" | "after" | undefined; shape?: "circular" | "rounded" | "square" | undefined; size?: ButtonSize | undefined; }> & Omit<CarouselButtonSlots, "root"> & Omit<{ as?: "button" | undefined; } & Omit<Omit<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & { ref?: ((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null | undefined; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { navType?: "next" | "prev" | undefined; }) | (Partial<Omit<ButtonSlots, "root"> & Omit<{ as: "a"; } & Omit<Omit<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, "ref"> & { ref?: ((instance: HTMLAnchorElement | null) => void) | RefObject<HTMLAnchorElement> | null | undefined; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { appearance?: "outline" | "subtle" | "secondary" | "primary" | "transparent" | undefined; disabledFocusable?: boolean | undefined; disabled?: boolean | undefined; iconPosition?: "before" | "after" | undefined; shape?: "circular" | "rounded" | "square" | undefined; size?: ButtonSize | undefined; }> & Omit<CarouselButtonSlots, "root"> & Omit<{ as?: "button" | undefined; } & Omit<Omit<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & { ref?: ((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null | undefined; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { navType?: "next" | "prev" | undefined; }) | (Partial<Omit<ButtonSlots, "root"> & Omit<{ as: "a"; } & Omit<Omit<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, "ref"> & { ref?: ((instance: HTMLAnchorElement | null) => void) | RefObject<HTMLAnchorElement> | null | undefined; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { appearance?: "outline" | "subtle" | "secondary" | "primary" | "transparent" | undefined; disabledFocusable?: boolean | undefined; disabled?: boolean | undefined; iconPosition?: "before" | "after" | undefined; shape?: "circular" | "rounded" | "square" | undefined; size?: ButtonSize | undefined; }> & Omit<CarouselButtonSlots, "root"> & Omit<{ as: "a"; } & Omit<Omit<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, "ref"> & { ref?: ((instance: HTMLAnchorElement | null) => void) | RefObject<HTMLAnchorElement> | null | undefined; }, "children"> & { children?: any; } & Pick<ARIAButtonProps<ARIAButtonType>, "disabled" | "disabledFocusable">, "ref"> & { navType?: "next" | "prev" | undefined; })> | null | undefined;

  prevTooltip?: WithSlotShorthandValue<TooltipProps> | null;

  ref?: Ref<HTMLDivElement>;

  style?: CSSProperties;
}

CarouselNavImageButton API

A variant child element of CarouselNav, a singular image button that displays a preview of card content and will set the carousels active value on click.

interface CarouselNavImageButtonProps {
  as?: "a" | "button" | "div";

  children?: any;

  className?: string;

  disabled?: boolean;

  /**
   * When set, allows the button to be focusable even when it has been disabled.
   * This is used in scenarios where it is important to keep a consistent tab order
   * for screen reader and keyboard users. The primary example of this
   * pattern is when the disabled button is in a menu or a commandbar and is seldom used for standalone buttons.
   * @default false
   */
  disabledFocusable?: boolean;

  /**
   * Required: The image within the button
   */
  image: { as?: "img" | undefined; } & Omit<Omit<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, "ref"> & { ref?: ((instance: HTMLImageElement | null) => void) | RefObject<HTMLImageElement> | null | undefined; }, "children"> & { children?: undefined; };

  ref?: Ref<HTMLAnchorElement | HTMLButtonElement | HTMLDivElement>;

  style?: CSSProperties;
}

CarouselSlider API

CarouselSlider component - The viewport window that CarouselCards are contained within.

interface CarouselSliderProps {
  as?: "div";

  /**
   * cardFocus sets the carousel slider as a focus group,
   * enabling left/right navigation of elements.
   *
   * This will also be passed into CarouselCards via context and set the appropriate focus attributes
   *
   * Defaults: false
   */
  cardFocus?: boolean;

  children?: any;

  className?: string;

  ref?: Ref<HTMLDivElement>;

  style?: CSSProperties;
}

CarouselViewport API

CarouselViewport component - TODO: add more docs

interface CarouselViewportProps {
  as?: "div";

  children?: any;

  className?: string;

  ref?: Ref<HTMLDivElement>;

  style?: CSSProperties;
}