Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Carousel): remove scale animation, add hasEdgeFade + padding props, fix hasButtons (#2566)

Cindy Zhang307d4ee2245c
diff --git a/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsx b/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsx
index 23fe3ba3fe..7a03ae740f 100644
--- a/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsx
+++ b/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsx
@@ -304,44 +304,15 @@ export function ThemingShowcase() {
<HeaderLinks />
</XDSHStack>
- {/* Carousel customisations that aren't expressible through
- XDSCarousel's prop surface. Scoped via the aria-label of
- *this* carousel so other XDSCarousel elsewhere in the
- docsite are unaffected. Rules only exist while
- ThemingShowcase is mounted (landing route only).
+ {/* Scroller padding that aligns the first tile to the heading
+ text column. This is a layout concern (not chrome) so it
+ remains as a scoped style targeting this carousel's scroller.
- TODO(xds#2509): Remove this block once XDSCarousel ships
- `hasEdgeFade` / `hasScaleAnimation` props and a reliable
- `hasButtons={false}`. Tracking issue:
- https://github.com/facebookexperimental/xds/issues/2509
-
- 1. Hide XDSCarousel's built-in prev/next pills — our own
- controls render in the header row. `hasButtons={false}`
- prop is intermittently flaky across HMR/popover states,
- so we belt-and-suspender with CSS targeting the
- popover-portal'd buttons by their aria-label.
-
- 2. Strip XDSCarousel's mask-image edge fade. The default
- reads as a smudgy band; full-bleed filmstrip uses the
- clean viewport clip instead.
-
- 3. Disable the scroll-driven 0.85→1.0→0.85 scale animation
- on each item — reads as inconsistent sizing rather than
- a helpful focus cue when each tile has its own theme.
-
- 4. Add left-padding equal to the page gutter so the FIRST
- tile aligns with the heading column's left edge instead
- of sitting flush against the viewport (the right end
- stays flush so the last tile clips at the viewport edge,
- signalling "more").
+ TODO: Consider a `scrollerXstyle` prop or padding prop on
+ XDSCarousel if this pattern recurs in other full-bleed usages.
*/}
<style>{`
- [popover]:has([aria-label="Scroll left"]),
- [popover]:has([aria-label="Scroll right"]) {
- display: none !important;
- }
[aria-label="Available themes"] > div:first-child {
- mask-image: none !important;
/* Gutter that aligns the first tile to the heading text
leading edge. Applied as padding on the scroller (not
a margin on the wrapper) so the gutter is INSIDE the
@@ -359,9 +330,6 @@ export function ThemingShowcase() {
padding-inline-end: ${CONTENT_GUTTER_FORMULA} !important;
scroll-padding-inline-end: ${CONTENT_GUTTER_FORMULA} !important;
}
- [aria-label="Available themes"] > div > div {
- animation: none !important;
- }
`}</style>
<div {...stylex.props(styles.carouselWrap)}>
@@ -369,7 +337,8 @@ export function ThemingShowcase() {
aria-label="Available themes"
gap={4}
hasSnap
- hasButtons={false}>
+ hasButtons={false}
+ hasEdgeFade={false}>
{themePackages.map(pkg => {
const theme = themeObjects[pkg.name];
if (!theme) {
diff --git a/packages/core/src/Carousel/XDSCarousel.test.tsx b/packages/core/src/Carousel/XDSCarousel.test.tsx
index f1378088d0..fb2ead72b0 100644
--- a/packages/core/src/Carousel/XDSCarousel.test.tsx
+++ b/packages/core/src/Carousel/XDSCarousel.test.tsx
@@ -56,4 +56,26 @@ describe('XDSCarousel', () => {
const el = screen.getByTestId('cls-test');
expect(el.className).toContain('xds-carousel');
});
+
+ it('does not render button layer when hasButtons={false}', () => {
+ render(
+ <XDSCarousel hasButtons={false} aria-label="No buttons">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </XDSCarousel>,
+ );
+ expect(screen.queryByLabelText('Scroll left')).not.toBeInTheDocument();
+ expect(screen.queryByLabelText('Scroll right')).not.toBeInTheDocument();
+ });
+
+ it('renders buttons by default', () => {
+ render(
+ <XDSCarousel aria-label="With buttons">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </XDSCarousel>,
+ );
+ expect(screen.getByLabelText('Scroll left')).toBeInTheDocument();
+ expect(screen.getByLabelText('Scroll right')).toBeInTheDocument();
+ });
});
diff --git a/packages/core/src/Carousel/XDSCarousel.tsx b/packages/core/src/Carousel/XDSCarousel.tsx
index c4c41b6f0a..37bed3a59a 100644
--- a/packages/core/src/Carousel/XDSCarousel.tsx
+++ b/packages/core/src/Carousel/XDSCarousel.tsx
@@ -31,6 +31,7 @@ import {useXDSLayer} from '../Layer';
import {useScrollOverflow} from '../hooks/useScrollOverflow';
import type {XDSBaseProps} from '../XDSBaseProps';
import {xdsClassName, mergeProps, mergeRefs} from '../utils';
+import type {SpacingStep} from '../utils/types';
export interface XDSCarouselProps extends XDSBaseProps<HTMLDivElement> {
ref?: React.Ref<HTMLDivElement>;
@@ -46,11 +47,28 @@ export interface XDSCarouselProps extends XDSBaseProps<HTMLDivElement> {
* @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 scroll-snap on items. Each direct child snaps to the start edge.
* @default false
*/
hasSnap?: boolean;
+ /**
+ * 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'
@@ -107,21 +125,6 @@ const styles = stylex.create({
scrollSnapAlign: 'start',
display: 'flex',
flexShrink: 0,
- // Entry: 0% = item just touching edge, ~15% = item half in view, ~30% = fully in view
- // Exit mirrors in reverse. Scale down only while partially out of view.
- animationName: stylex.keyframes({
- '0%': {transform: 'scale(0.85)'},
- '15%': {transform: 'scale(1)'},
- '85%': {transform: 'scale(1)'},
- '100%': {transform: 'scale(0.85)'},
- }),
- animationTimeline: 'view(inline)',
- animationRange: 'cover',
- animationFillMode: 'both',
- animationDuration: {
- default: null,
- '@media (prefers-reduced-motion: reduce)': '0ms',
- },
},
// Overlay on top layer — covers the carousel anchor area
buttonOverlay: {
@@ -169,6 +172,20 @@ const gapStyles = stylex.create({
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']},
+});
+
// =============================================================================
// Component
// =============================================================================
@@ -196,7 +213,9 @@ export function XDSCarousel({
children,
gap = 1,
hasButtons = true,
+ hasEdgeFade = true,
hasSnap = false,
+ padding,
'aria-label': ariaLabel = 'Carousel',
xstyle,
className,
@@ -242,14 +261,15 @@ export function XDSCarousel({
});
}, []);
- const fadeStyle =
- overflowStart && overflowEnd
+ const fadeStyle = hasEdgeFade
+ ? overflowStart && overflowEnd
? styles.fadeBoth
: overflowStart
? styles.fadeStart
: overflowEnd
? styles.fadeEnd
- : null;
+ : null
+ : null;
const coverStyle: React.CSSProperties = {
positionArea: 'center',
@@ -276,6 +296,7 @@ export function XDSCarousel({
{...stylex.props(
styles.scroller,
gapStyles[gap],
+ padding != null && paddingStyles[padding],
hasSnap && styles.snap,
fadeStyle,
)}>
@@ -284,48 +305,49 @@ export function XDSCarousel({
))}
</div>
- {layer.render(
- <>
- <div
- {...stylex.props(
- styles.buttonPill,
- styles.buttonPillStart,
- !overflowStart && styles.buttonHidden,
- )}>
- <XDSButton
- icon={<XDSIcon icon="chevronLeft" size="xsm" />}
- label="Scroll left"
- variant="ghost"
- size="sm"
- isIconOnly
- onClick={() => scrollBy(-1)}
- xstyle={styles.buttonRadiusOverride}
- />
- </div>
- <div
- {...stylex.props(
- styles.buttonPill,
- styles.buttonPillEnd,
- !overflowEnd && styles.buttonHidden,
- )}>
- <XDSButton
- icon={<XDSIcon icon="chevronRight" size="xsm" />}
- label="Scroll right"
- variant="ghost"
- size="sm"
- isIconOnly
- onClick={() => scrollBy(1)}
- xstyle={styles.buttonRadiusOverride}
- />
- </div>
- </>,
- {
- placement: 'below',
- alignment: 'center',
- style: coverStyle,
- xstyle: styles.buttonOverlay,
- },
- )}
+ {hasButtons &&
+ layer.render(
+ <>
+ <div
+ {...stylex.props(
+ styles.buttonPill,
+ styles.buttonPillStart,
+ !overflowStart && styles.buttonHidden,
+ )}>
+ <XDSButton
+ icon={<XDSIcon icon="chevronLeft" size="xsm" />}
+ label="Scroll left"
+ variant="ghost"
+ size="sm"
+ isIconOnly
+ onClick={() => scrollBy(-1)}
+ xstyle={styles.buttonRadiusOverride}
+ />
+ </div>
+ <div
+ {...stylex.props(
+ styles.buttonPill,
+ styles.buttonPillEnd,
+ !overflowEnd && styles.buttonHidden,
+ )}>
+ <XDSButton
+ icon={<XDSIcon icon="chevronRight" size="xsm" />}
+ label="Scroll right"
+ variant="ghost"
+ size="sm"
+ isIconOnly
+ onClick={() => scrollBy(1)}
+ xstyle={styles.buttonRadiusOverride}
+ />
+ </div>
+ </>,
+ {
+ placement: 'below',
+ alignment: 'center',
+ style: coverStyle,
+ xstyle: styles.buttonOverlay,
+ },
+ )}
</div>
);
}