An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file Carousel.tsx
* @input Uses React, StyleX, useScrollOverflow, useLayer, Button, Icon, theme tokens
* @output Exports Carousel component
* @position Horizontal scroll container with fade-edge overflow indication,
* optional prev/next buttons on the top layer, scroll-snap, a 1px
* visual bleed allowance for child selection indicators, and Shift + wheel
* mapping so mouse users can scroll horizontally. Supports optional
* wrap-around looping and an imperative handle (handleRef) for programmatic
* scroll control. Exposes APG
* carousel semantics: the root is a labelled region with
* aria-roledescription="carousel" and each item wrapper is a group with
* aria-roledescription="slide" named "Slide N of M". The scroll area is a
* group named like the carousel and a tab stop only while its content
* overflows (AST-025 FR12).
*
* SYNC: When modified, update:
* - /packages/core/src/Carousel/index.ts (exports)
* - /apps/storybook/stories/Carousel.stories.tsx
* - /packages/cli/assets/templates/blocks/components/Carousel/ (showcase blocks)
*/
import {
type ReactNode,
useRef,
useCallback,
useEffect,
useImperativeHandle,
useState,
Children,
isValidElement,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
spacingVars,
colorVars,
shadowVars,
radiusVars,
durationVars,
easeVars,
focusVars,
} from '../theme/tokens.stylex';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {
focusOwnerProps,
focusWithinOwnerOverlay,
} from '../privateAttributes/focusOwner.stylex';
import {Button} from '../Button';
import {Icon} from '../Icon';
import {useLayer} from '../Layer';
import {useAttachment} from '../hooks/useAttachment';
import {useShownScrollOverflow} from '../hooks/useScrollOverflow';
import {isRtlElement} from '../hooks/isRtlElement';
import type {BaseProps} from '../BaseProps';
import {mergeProps, rtlStyles} from '../utils';
import type {SpacingStep} from '../utils/types';
import {themeProps} from '../utils/themeProps';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {
attachSnapPaging,
isSnapPaging,
moveHeldSnapPaging,
moveSnapPaging,
nearestStop,
type SnapPaging,
snapStops,
} from '../SnapPaging/snapPagingValue';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Carousel/Carousel.generated';
registerEnglishFallback(english);
/**
* Imperative control surface for the Carousel, accessed via the `handleRef`
* prop. Methods drive the same native-scroll machinery as the built-in
* buttons, so they respect RTL, reduced-motion, and `hasLoop`.
*/
export interface CarouselHandle {
/**
* Scroll forward by roughly one viewport. With `hasLoop`, wraps to the
* start once the end is reached.
*/
scrollNext(): void;
/**
* Scroll backward by roughly one viewport. With `hasLoop`, wraps to the
* end once the start is reached.
*/
scrollPrev(): void;
/**
* Scroll the item at the given 0-based index to the start edge. The index
* is clamped to the item range, and only the carousel scrolls — the page
* position is left untouched.
*/
scrollTo(index: number): void;
/**
* Whether there is scrollable content past the trailing edge. With
* `hasLoop`, returns true whenever the content overflows, since wrapping
* is always available. Reads live state — safe to call in an event handler.
*/
canScrollNext(): boolean;
/**
* Whether there is scrollable content past the leading edge. With
* `hasLoop`, returns true whenever the content overflows. Reads live state.
*/
canScrollPrev(): boolean;
}
export interface CarouselProps extends BaseProps<HTMLDivElement> {
ref?: React.Ref<HTMLDivElement>;
/**
* Imperative handle for programmatic scroll control. Exposes scrollNext,
* scrollPrev, scrollTo, and the canScrollNext/canScrollPrev queries.
*/
handleRef?: React.Ref<CarouselHandle>;
/** Carousel items — rendered in a horizontal scroll container. */
children: ReactNode;
/**
* Gap between items using spacing scale tokens.
* @default 1
*/
gap?: 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4;
/**
* Show prev/next navigation buttons when content is scrollable.
* @default true
*/
hasButtons?: boolean;
/**
* Show gradient edge-fade mask when content overflows, signalling that
* more items exist off-screen. Can be suppressed when items have
* full-fidelity surfaces that look broken when masked.
* @default true
*/
hasEdgeFade?: boolean;
/**
* Enable wrap-around scrolling. When the content overflows, pressing Next
* at the end scrolls back to the start, and Prev at the start scrolls to
* the end — for both the built-in buttons and the imperative handle. The
* navigation buttons stay visible at both edges instead of hiding, since a
* scroll is always available. Has no effect when the content fits without
* overflowing.
* @default false
*/
hasLoop?: boolean;
/**
* Snap each item to the start edge. `true` (written `hasSnap`) uses native
* CSS scroll snap. A `useSnapPaging()` value adds iOS paging on the same
* stops, under a finger and on a trackpad swipe. A flick moves one view, or
* one item with `useSnapPaging({pages: 'item'})`. Only that value loads the
* paging code.
* @default false
*/
hasSnap?: boolean | SnapPaging;
/**
* Inline padding on the scroll container. Applied as padding-inline
* so the gutter is inside the scrollable area — items can scroll fully
* into the padded region. Also sets matching scroll-padding so snap
* points align to the content edge rather than the viewport edge.
*
* Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
* @default undefined (no padding)
*/
padding?: SpacingStep;
/**
* Accessible label for the carousel region.
* @default 'Carousel'
*/
'aria-label'?: string;
'data-testid'?: string;
}
// =============================================================================
// Styles
// =============================================================================
const styles = stylex.create({
root: {
position: 'relative',
display: 'flex',
alignItems: 'center',
minWidth: 0,
maxWidth: '100%',
overflow: 'clip',
overflowClipMargin: '1px',
},
scroller: {
display: 'flex',
alignItems: 'center',
overflowX: 'auto',
overflowY: 'hidden',
/* eslint-disable @astryx/no-hardcoded-styles -- 1px bleed for tab indicator; no token at this size */
paddingBottom: '1px',
marginBottom: '-1px',
/* eslint-enable @astryx/no-hardcoded-styles */
overscrollBehaviorX: 'contain',
scrollBehavior: {
default: 'smooth',
'@media (prefers-reduced-motion: reduce)': 'auto',
},
scrollbarWidth: 'none',
maskImage: 'none',
},
fadeStart: {
maskImage: {
default: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
':is([dir="rtl"] *)': `linear-gradient(to left, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
},
},
fadeEnd: {
maskImage: {
default: `linear-gradient(to left, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
':is([dir="rtl"] *)': `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
},
},
fadeBoth: {
maskImage: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']}, black calc(100% - ${spacingVars['--spacing-1']}), rgba(0,0,0,0.3) calc(100% - 2px), transparent 100%)`,
},
snap: {
scrollSnapType: 'x mandatory',
},
item: {
scrollSnapAlign: 'start',
display: 'flex',
flexShrink: 0,
},
// Overlay on top layer — covers the carousel anchor area
buttonOverlay: {
display: 'flex',
justifyContent: 'space-between',
alignItems: 'center',
pointerEvents: 'none',
},
buttonPill: {
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
backgroundColor: colorVars['--color-background-popover'],
borderRadius: radiusVars['--radius-full'],
boxShadow: shadowVars['--shadow-med'],
pointerEvents: 'auto',
opacity: 1,
transitionProperty: 'opacity',
transitionDuration: durationVars['--duration-fast'],
transitionTimingFunction: easeVars['--ease-standard'],
},
buttonPillStart: {
transform: {
default: 'translateX(-50%)',
':is([dir="rtl"] *)': 'translateX(50%)',
},
},
buttonPillEnd: {
transform: {
default: 'translateX(50%)',
':is([dir="rtl"] *)': 'translateX(-50%)',
},
},
buttonHidden: {
opacity: 0,
pointerEvents: 'none' as const,
},
// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion, @typescript-eslint/consistent-type-assertions -- CSS custom property requires type widening for StyleX
buttonRadiusOverride: {
'--_button-radius': radiusVars['--radius-full'],
} as Record<string, string>,
});
const gapStyles = stylex.create({
0: {gap: spacingVars['--spacing-0']},
0.5: {gap: spacingVars['--spacing-0-5']},
1: {gap: spacingVars['--spacing-1']},
1.5: {gap: spacingVars['--spacing-1-5']},
2: {gap: spacingVars['--spacing-2']},
3: {gap: spacingVars['--spacing-3']},
4: {gap: spacingVars['--spacing-4']},
});
const paddingStyles = stylex.create({
0: {
paddingInline: spacingVars['--spacing-0'],
scrollPaddingInline: spacingVars['--spacing-0'],
},
0.5: {
paddingInline: spacingVars['--spacing-0-5'],
scrollPaddingInline: spacingVars['--spacing-0-5'],
},
1: {
paddingInline: spacingVars['--spacing-1'],
scrollPaddingInline: spacingVars['--spacing-1'],
},
1.5: {
paddingInline: spacingVars['--spacing-1-5'],
scrollPaddingInline: spacingVars['--spacing-1-5'],
},
2: {
paddingInline: spacingVars['--spacing-2'],
scrollPaddingInline: spacingVars['--spacing-2'],
},
3: {
paddingInline: spacingVars['--spacing-3'],
scrollPaddingInline: spacingVars['--spacing-3'],
},
4: {
paddingInline: spacingVars['--spacing-4'],
scrollPaddingInline: spacingVars['--spacing-4'],
},
5: {
paddingInline: spacingVars['--spacing-5'],
scrollPaddingInline: spacingVars['--spacing-5'],
},
6: {
paddingInline: spacingVars['--spacing-6'],
scrollPaddingInline: spacingVars['--spacing-6'],
},
8: {
paddingInline: spacingVars['--spacing-8'],
scrollPaddingInline: spacingVars['--spacing-8'],
},
10: {
paddingInline: spacingVars['--spacing-10'],
scrollPaddingInline: spacingVars['--spacing-10'],
},
});
/**
* Runs one of Carousel's own calls into the paging: a scroll call or the
* detach. Such a call can run inside React's commit, so a report it raises
* takes React's scheduling.
*/
function ownCall<T>(depth: {current: number}, run: () => T): T {
depth.current += 1;
try {
return run();
} finally {
depth.current -= 1;
}
}
/**
* Where an edge press under snap paging goes from offset `at`: about one view
* on, to the nearest stop and at least one stop on. With `wraps`, a press past
* an edge goes to the opposite edge.
*/
function pagingStep(
el: HTMLElement,
at: number,
end: number,
direction: -1 | 1,
wraps: boolean,
): number {
if (wraps && (direction === 1 ? at >= end - 0.5 : at <= 0.5)) {
return direction === 1 ? 0 : end;
}
const firstChild = el.firstElementChild as HTMLElement | null;
const itemWidth = firstChild ? firstChild.offsetWidth : 0;
const amount = el.clientWidth - itemWidth * 0.5;
const stops = snapStops(el, at, end);
const nearest = nearestStop(
stops,
at + direction * Math.max(amount, itemWidth),
);
if (direction === 1 && nearest <= at + 0.5) {
return stops.find(stop => stop > at + 0.5) ?? nearest;
}
if (direction === -1 && nearest >= at - 0.5) {
return [...stops].reverse().find(stop => stop < at - 0.5) ?? nearest;
}
return nearest;
}
// =============================================================================
// Component
// =============================================================================
/**
* Horizontal scroll container with fade-edge overflow indication and
* optional navigation buttons.
*
* Wraps any content in a scrollable row. When content overflows, gradient
* fades appear at the edges to signal more items exist. When content overflows, prev/next buttons appear at the edges,
* rendered on the top layer via Layer so they escape any parent overflow
* clipping.
*
* @example
* ```
* <Carousel gap={1}>
* <Thumbnail src="/a.jpg" alt="A" />
* <Thumbnail src="/b.jpg" alt="B" />
* <Thumbnail src="/c.jpg" alt="C" />
* </Carousel>
* ```
*/
export function Carousel({
ref,
handleRef,
children,
gap = 1,
hasButtons = true,
hasEdgeFade = true,
hasLoop = false,
hasSnap = false,
padding,
'aria-label': ariaLabelFromProps,
xstyle,
className,
style,
'data-testid': testId,
...htmlProps
}: CarouselProps) {
const t = useComponentTranslator();
const ariaLabel = ariaLabelFromProps ?? t('@astryx.carousel.label');
const scrollElRef = useRef<HTMLElement | null>(null);
const runningOwnCallsRef = useRef(0);
const startButtonRef = useRef<HTMLButtonElement>(null);
const endButtonRef = useRef<HTMLButtonElement>(null);
// Which nav button last held focus, and what the overflow state was on the
// previous render. Together they are how the Effect below recognises the one
// transition it is allowed to act on.
const focusedNavRef = useRef<'start' | 'end' | null>(null);
const prevCanScrollRef = useRef<{start: boolean; end: boolean} | null>(null);
const {scrollRef, followShown, overflowStart, overflowEnd, hasOverflow} =
useShownScrollOverflow();
// Children.toArray drops null/undefined/boolean children and assigns
// stable keys, so slide numbering ("Slide N of M") matches what actually
// renders even when some children are conditionally omitted.
const slides = Children.toArray(children);
const layer = useLayer({
mode: 'context',
lightDismiss: false,
});
// Syncs the layer with `hasButtons`.
useEffect(() => {
if (hasButtons) {
layer.show();
} else {
layer.hide();
}
}, [hasButtons, layer]);
const composedRef = useCallback(
(el: HTMLDivElement | null) => {
scrollElRef.current = el;
scrollRef(el);
},
[scrollRef],
);
// Snap paging attaches once, with the first value. A new value on a later
// render does not restart a settle or attach again.
const snapPaging = isSnapPaging(hasSnap) ? hasSnap : null;
const isPaging = snapPaging != null;
const [attachedPaging, setAttachedPaging] = useState(snapPaging);
if ((attachedPaging != null) !== isPaging) {
setAttachedPaging(snapPaging);
}
// Attaches snap paging to the scroll area, and follows a replaced one.
// While the paging holds the row, the edges follow the row as shown.
useAttachment(
scrollElRef,
scroller => {
if (attachedPaging == null) {
return () => {};
}
const detach = attachSnapPaging(attachedPaging, scroller, held =>
followShown(held, runningOwnCallsRef.current === 0),
);
return () => ownCall(runningOwnCallsRef, detach);
},
attachedPaging,
);
// React's wheel listener is passive, so it can't stop the browser's own
// scroll; this native one can. While a flick holds the row, the paging takes
// a wheel the gesture host leaves to the stop nearest its travel.
//
// A mouse wheel gives only deltaY. Shift + wheel is the convention for a
// horizontal scroll. A trackpad gives deltaX, so the browser scrolls the row.
// A row that fits gets no listener, so a page scroll over it does not wait
// for script. The listener reads no style or layout unless a flick holds
// the row.
useAttachment(
scrollElRef,
el => {
if (!hasOverflow) {
return () => {};
}
const onWheel = (event: WheelEvent) => {
if (event.defaultPrevented) {
return;
}
const delta = event.deltaX || (event.shiftKey ? event.deltaY : 0);
if (
delta !== 0 &&
moveHeldSnapPaging(el, (at, end) =>
nearestStop(
snapStops(el, at, end),
at + (isRtlElement(el) ? -delta : delta),
),
)
) {
event.preventDefault();
event.stopPropagation();
return;
}
if (!event.shiftKey || event.deltaY === 0 || event.deltaX !== 0) {
return;
}
event.preventDefault();
el.scrollBy({left: event.deltaY, behavior: 'auto'});
};
el.addEventListener('wheel', onWheel, {passive: false});
return () => el.removeEventListener('wheel', onWheel);
},
hasOverflow,
);
const scrollBy = useCallback(
(direction: -1 | 1) => {
const el = scrollElRef.current;
if (!el) {
return;
}
// Under snap paging the paging moves the row, held or at rest. A touch
// then catches the move, and the release rests on a page.
if (
ownCall(runningOwnCallsRef, () =>
moveSnapPaging(el, (at, end) =>
pagingStep(el, at, end, direction, hasLoop && hasOverflow),
),
)
) {
return;
}
// Respect the user's reduced-motion preference — mirrors the CSS
// scroll-behavior override so button-driven scrolling doesn't animate
// for users who opted out of motion.
const prefersReducedMotion =
typeof window !== 'undefined' &&
typeof window.matchMedia === 'function' &&
window.matchMedia('(prefers-reduced-motion: reduce)').matches;
const behavior = prefersReducedMotion ? 'auto' : 'smooth';
// Under RTL the scroll axis is inverted (start is scrollLeft 0, the end
// is negative), so flip the physical delta sign.
const rtlSign = isRtlElement(el) ? -1 : 1;
// Wrap-around: when looping over overflowing content, a press that would
// run past an edge jumps to the opposite edge instead. Overshoot by the
// full scroll width in the opposite logical direction and let the browser
// clamp to the far edge — this reuses the same RTL sign convention as a
// normal scroll, so it stays direction-correct without special-casing.
if (hasLoop && hasOverflow) {
const atEnd = direction === 1 && !overflowEnd;
const atStart = direction === -1 && !overflowStart;
if (atEnd || atStart) {
el.scrollBy({left: rtlSign * -direction * el.scrollWidth, behavior});
return;
}
}
const firstChild = el.firstElementChild as HTMLElement | null;
const itemWidth = firstChild ? firstChild.offsetWidth : 0;
const amount = el.clientWidth - itemWidth * 0.5;
if (isPaging) {
// Snap paging lands the step on the nearest stop, at least one stop
// on, in every engine. A native snap after scrollBy picks its own.
const end = Math.max(0, el.scrollWidth - el.clientWidth);
const next = pagingStep(
el,
Math.abs(el.scrollLeft),
end,
direction,
false,
);
el.scrollTo({left: rtlSign * next, behavior});
return;
}
el.scrollBy({
// `direction` is the logical intent (-1 = toward content start, +1 =
// toward content end).
left: rtlSign * direction * Math.max(amount, itemWidth),
behavior,
});
},
[hasLoop, hasOverflow, overflowStart, overflowEnd, isPaging],
);
const scrollToIndex = useCallback((index: number) => {
const el = scrollElRef.current;
const items = el?.children;
if (!el || !items || items.length === 0) {
return;
}
const clamped = Math.max(0, Math.min(index, items.length - 1));
const target = items[clamped] as HTMLElement;
const prefersReducedMotion =
typeof window !== 'undefined' &&
typeof window.matchMedia === 'function' &&
window.matchMedia('(prefers-reduced-motion: reduce)').matches;
// Bring the item to the start edge by scrolling the container by the
// measured gap between the item and the container edge. Using scrollBy
// (not scrollIntoView) keeps the scroll contained to the carousel and
// never moves ancestors or the page. In RTL the start edge is the right
// edge, so align the trailing edges instead of the leading ones.
const containerRect = el.getBoundingClientRect();
const itemRect = target.getBoundingClientRect();
const delta = isRtlElement(el)
? itemRect.right - containerRect.right
: itemRect.left - containerRect.left;
// Under snap paging the row goes to the item's stop, inside the scroll
// padding, so the hand-back's snap does not pull it back.
if (
ownCall(runningOwnCallsRef, () =>
moveSnapPaging(el, (at, end) =>
nearestStop(
snapStops(el, at, end),
at + (isRtlElement(el) ? -delta : delta),
),
),
)
) {
return;
}
el.scrollBy({
left: delta,
behavior: prefersReducedMotion ? 'auto' : 'smooth',
});
}, []);
useImperativeHandle(
handleRef,
() => ({
scrollNext: () => scrollBy(1),
scrollPrev: () => scrollBy(-1),
scrollTo: (index: number) => scrollToIndex(index),
// With loop, either direction is reachable whenever the content
// overflows; otherwise reflect the live per-edge overflow state.
canScrollNext: () => (hasLoop ? hasOverflow : overflowEnd),
canScrollPrev: () => (hasLoop ? hasOverflow : overflowStart),
}),
[scrollBy, scrollToIndex, hasLoop, hasOverflow, overflowStart, overflowEnd],
);
// With loop, the buttons stay reachable at both edges as long as there's
// something to scroll; without loop they follow the per-edge overflow state.
const canScrollStart = hasLoop && hasOverflow ? true : overflowStart;
const canScrollEnd = hasLoop && hasOverflow ? true : overflowEnd;
// Keep the keyboard user where they are when a nav button disables under
// them. The browser drops focus off a control it disables, so reaching an
// edge used to land the user on <body> and cost them their place in the page.
//
// This is an Effect on purpose, and the exception is narrow. The thing that
// disables the button IS this state transition, so it is the only correct
// trigger: three attempts to predict it from the press -- the position after
// the scroll, the position before it plus the step, and the settled position
// reported by `scrollend` -- were each wrong somewhere, under reduced motion,
// under mandatory scroll-snap, and on a browser that never fires the event.
// Ruled acceptable by the
// maintainer, 2026-08-27, on the conditions encoded below: it acts only on
// the transition that newly disables the focused button, it moves focus and
// nothing else, and it cannot fire twice for one transition.
//
// Which button the person is on is tracked by the buttons' own focus and blur
// handlers, and the blur has to ignore the one the commit itself causes: a
// tracker that outlived the person let a later edge -- a swipe, a resize, no
// press at all -- pull their focus back onto a control they never chose.
useEffect(() => {
const previous = prevCanScrollRef.current;
prevCanScrollRef.current = {start: canScrollStart, end: canScrollEnd};
const side = focusedNavRef.current;
if (previous == null || side == null) {
return;
}
// Only the edge that just ran out, and only while it held focus. An edge
// that was already disabled, or one the user was not on, is not ours.
const wasEnabled = side === 'start' ? previous.start : previous.end;
const isEnabled = side === 'start' ? canScrollStart : canScrollEnd;
if (!wasEnabled || isEnabled) {
return;
}
const pressed =
side === 'start' ? startButtonRef.current : endButtonRef.current;
if (pressed == null) {
return;
}
// The browser has already blurred it, so focus reads as the body. Anything
// else means the user moved on themselves and this is not ours to redirect.
const active = pressed.ownerDocument.activeElement;
if (active !== pressed && active !== pressed.ownerDocument.body) {
return;
}
// The scroll area is the receiver (component:Carousel FR2). It takes focus
// programmatically even when it is out of the tab order.
const receiver = scrollElRef.current;
if (receiver == null) {
return;
}
// One move per transition: clearing the tracker first means a re-render or
// a StrictMode double-invoke re-runs this and returns at the `side == null`
// guard above.
focusedNavRef.current = null;
// preventScroll: a plain focus() scrolls its element into view, which on
// the scroll container cancels the scroll the press just started.
receiver.focus({preventScroll: true});
}, [canScrollStart, canScrollEnd]);
const fadeStyle = hasEdgeFade
? (hasLoop && hasOverflow) || (overflowStart && overflowEnd)
? styles.fadeBoth
: overflowStart
? styles.fadeStart
: overflowEnd
? styles.fadeEnd
: null
: null;
// Self-authored position styles (positioning: 'custom' below): a cover
// centered on the anchor, sized to it — direction-neutral by construction.
const coverStyle: React.CSSProperties = {
positionArea: 'center',
width: 'anchor-size(width)',
height: 'anchor-size(height)',
};
return (
<div
ref={useMergedRefs(ref, layer.ref as React.Ref<HTMLDivElement>)}
data-testid={testId}
{...htmlProps}
{...mergeProps(
themeProps('carousel'),
stylex.props(
styles.root,
// The scroller is the focus owner. Its edge-fade mask would cover a
// ring the root draws itself.
focusWithinOwnerOverlay,
xstyle,
),
className,
style,
)}
role="region"
aria-label={ariaLabel}
aria-roledescription="carousel">
<div
ref={composedRef}
// The scroll area takes keyboard scrolling (spec:AST-025 FR12): a
// group named like the carousel, in the tab order only while its
// content overflows. While it fits it still takes focus
// programmatically, for the edge buttons' hand-off (FR2).
role="group"
aria-label={ariaLabel}
tabIndex={hasOverflow ? 0 : -1}
{...focusOwnerProps}
{...mergeProps(
themeProps('carousel-scroller', {
gap,
padding,
snap: hasSnap ? 'snap' : null,
edgeFade: hasEdgeFade ? 'edge-fade' : null,
}),
stylex.props(
styles.scroller,
// A tab stop whose shared ring the root paints.
focusOutlineStyles.suppressed,
gapStyles[gap],
padding != null && paddingStyles[padding],
hasSnap && styles.snap,
fadeStyle,
),
)}>
{slides.map((child, index) => (
// APG carousel pattern: each slide container is a group with
// aria-roledescription="slide" and an "N of M" accessible name so
// ATs announce slide boundaries and position instead of anonymous
// generics.
<div
// eslint-disable-next-line @eslint-react/no-array-index-key -- index fallback only applies to text/number children, which are positional by definition; elements keep their Children.toArray keys
key={isValidElement(child) ? child.key : index}
role="group"
aria-roledescription="slide"
aria-label={t('@astryx.carousel.slideLabel', {
current: index + 1,
total: slides.length,
})}
{...stylex.props(styles.item)}>
{child}
</div>
))}
</div>
{hasButtons &&
layer.render(
<>
<div
// A hidden button is never a Tab stop or in the a11y tree. Its
// disabled state alone would keep it focusable.
inert={!canScrollStart || undefined}
{...stylex.props(
styles.buttonPill,
styles.buttonPillStart,
!canScrollStart && styles.buttonHidden,
)}>
<Button
ref={startButtonRef}
icon={
<Icon
icon="chevronLeft"
size="xsm"
xstyle={rtlStyles.mirror}
/>
}
label={t('@astryx.carousel.scrollLeft')}
variant="ghost"
size="sm"
isIconOnly
// Disabled when there's nothing to scroll toward. Keeps the
// button mounted (stable layout). The Effect above hands focus
// to the scroll area when the state behind this one flips it
// disabled.
isDisabled={!canScrollStart}
onFocus={() => {
focusedNavRef.current = 'start';
}}
onBlur={event => {
// A disabled button was blurred by the commit, not the person.
if (
event.currentTarget.getAttribute('aria-disabled') !== 'true'
) {
focusedNavRef.current = null;
}
}}
onClick={() => scrollBy(-1)}
xstyle={styles.buttonRadiusOverride}
/>
</div>
<div
// A hidden button is never a Tab stop or in the a11y tree. Its
// disabled state alone would keep it focusable.
inert={!canScrollEnd || undefined}
{...stylex.props(
styles.buttonPill,
styles.buttonPillEnd,
!canScrollEnd && styles.buttonHidden,
)}>
<Button
ref={endButtonRef}
icon={
<Icon
icon="chevronRight"
size="xsm"
xstyle={rtlStyles.mirror}
/>
}
label={t('@astryx.carousel.scrollRight')}
variant="ghost"
size="sm"
isIconOnly
// See "Scroll left" — disabled while visually hidden so the
// button stays mounted.
isDisabled={!canScrollEnd}
onFocus={() => {
focusedNavRef.current = 'end';
}}
onBlur={event => {
// A disabled button was blurred by the commit, not the person.
if (
event.currentTarget.getAttribute('aria-disabled') !== 'true'
) {
focusedNavRef.current = null;
}
}}
onClick={() => scrollBy(1)}
xstyle={styles.buttonRadiusOverride}
/>
</div>
</>,
{
positioning: 'custom',
style: coverStyle,
xstyle: styles.buttonOverlay,
},
)}
</div>
);
}
Carousel.displayName = 'Carousel';