Skip to content

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

TypeScript

fix(Carousel): Shift + vertical wheel scrolls horizontally (#4129) (#4192)

Cindy Zhang1d9a74d27d97
diff --git a/.changeset/carousel-shift-wheel-horizontal.md b/.changeset/carousel-shift-wheel-horizontal.md
new file mode 100644
index 0000000000..988566e8e3
--- /dev/null
+++ b/.changeset/carousel-shift-wheel-horizontal.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Carousel now scrolls horizontally when you hold Shift and scroll the mouse wheel. Trackpad users already got horizontal scroll for free; this brings standard mouse (vertical-only wheel) users to parity using the established Shift + wheel convention. Native trackpad horizontal scrolling and the prev/next buttons are unchanged.
+
+@cixzhang
diff --git a/packages/core/src/Carousel/Carousel.doc.mjs b/packages/core/src/Carousel/Carousel.doc.mjs
index 5c45aa2409..d05780e1c4 100644
--- a/packages/core/src/Carousel/Carousel.doc.mjs
+++ b/packages/core/src/Carousel/Carousel.doc.mjs
@@ -14,6 +14,7 @@ export const docs = {
{guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge, like a gallery or product list.'},
{guidance: true, description: 'Always provide an aria-label that describes what the carousel contains, like "Featured products" or "Team members".'},
{guidance: true, description: 'Use a consistent gap and item width so the carousel looks intentional, not like content overflowing by accident.'},
+ {guidance: true, description: 'Trust the built-in navigation: trackpad users can swipe horizontally, and mouse users can hold Shift while scrolling the wheel to move through items.'},
{guidance: false, description: 'Use a carousel for content every user must see. Not everyone scrolls horizontally, so put critical content above the fold.'},
{guidance: false, description: 'Auto-advance items. Let the user scroll at their own pace.'},
{guidance: false, description: 'Nest carousels. A carousel inside a carousel is confusing and breaks keyboard navigation.'},
diff --git a/packages/core/src/Carousel/Carousel.test.tsx b/packages/core/src/Carousel/Carousel.test.tsx
index 7a6c80e200..1a01b43d92 100644
--- a/packages/core/src/Carousel/Carousel.test.tsx
+++ b/packages/core/src/Carousel/Carousel.test.tsx
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent} from '@testing-library/react';
import {Carousel} from './Carousel';
// Mock ResizeObserver (not available in jsdom)
@@ -111,4 +111,99 @@ describe('Carousel', () => {
expect(left).toBeDisabled();
expect(right).toBeDisabled();
});
+
+ describe('Shift + wheel horizontal scroll', () => {
+ // jsdom doesn't lay out elements, so we fake an overflowing scroll
+ // container and capture scrollBy calls.
+ function getScroller() {
+ const region = screen.getByRole('region');
+ return region.firstElementChild as HTMLElement;
+ }
+
+ function makeOverflowing(el: HTMLElement) {
+ Object.defineProperty(el, 'scrollWidth', {
+ value: 500,
+ configurable: true,
+ });
+ Object.defineProperty(el, 'clientWidth', {
+ value: 200,
+ configurable: true,
+ });
+ }
+
+ it('maps Shift + vertical wheel to horizontal scroll', () => {
+ render(
+ <Carousel aria-label="Wheel">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </Carousel>,
+ );
+ const scroller = getScroller();
+ makeOverflowing(scroller);
+ const scrollBy = vi.fn();
+ scroller.scrollBy = scrollBy;
+
+ fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 0});
+
+ expect(scrollBy).toHaveBeenCalledWith({left: 120, behavior: 'auto'});
+ });
+
+ it('does not translate wheel without Shift held', () => {
+ render(
+ <Carousel aria-label="Wheel">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </Carousel>,
+ );
+ const scroller = getScroller();
+ makeOverflowing(scroller);
+ const scrollBy = vi.fn();
+ scroller.scrollBy = scrollBy;
+
+ fireEvent.wheel(scroller, {shiftKey: false, deltaY: 120, deltaX: 0});
+
+ expect(scrollBy).not.toHaveBeenCalled();
+ });
+
+ it('leaves native horizontal wheel deltas alone', () => {
+ // Trackpads emit deltaX directly — don't double-handle those.
+ render(
+ <Carousel aria-label="Wheel">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </Carousel>,
+ );
+ const scroller = getScroller();
+ makeOverflowing(scroller);
+ const scrollBy = vi.fn();
+ scroller.scrollBy = scrollBy;
+
+ fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 40});
+
+ expect(scrollBy).not.toHaveBeenCalled();
+ });
+
+ it('does not intercept when there is no horizontal overflow', () => {
+ render(
+ <Carousel aria-label="Wheel">
+ <div>Item 1</div>
+ </Carousel>,
+ );
+ const scroller = getScroller();
+ Object.defineProperty(scroller, 'scrollWidth', {
+ value: 200,
+ configurable: true,
+ });
+ Object.defineProperty(scroller, 'clientWidth', {
+ value: 200,
+ configurable: true,
+ });
+ const scrollBy = vi.fn();
+ scroller.scrollBy = scrollBy;
+
+ fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 0});
+
+ expect(scrollBy).not.toHaveBeenCalled();
+ });
+ });
});
diff --git a/packages/core/src/Carousel/Carousel.tsx b/packages/core/src/Carousel/Carousel.tsx
index 4796e11018..6f2de18f9a 100644
--- a/packages/core/src/Carousel/Carousel.tsx
+++ b/packages/core/src/Carousel/Carousel.tsx
@@ -7,8 +7,9 @@
* @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, and a 1px
- * visual bleed allowance for child selection indicators.
+ * 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.
*
* SYNC: When modified, update:
* - /packages/core/src/Carousel/index.ts (exports)
@@ -290,6 +291,31 @@ export function Carousel({
[scrollRef],
);
+ // Map Shift + vertical wheel to horizontal scroll. Trackpads emit
+ // horizontal deltas natively, but a standard mouse only produces deltaY —
+ // so mouse users can't wheel-scroll a horizontal container. Shift + wheel
+ // is the long-established convention for horizontal scroll containers; we
+ // honor it by translating the vertical delta into a horizontal scroll.
+ //
+ // Only kicks in when Shift is held and the wheel is purely vertical
+ // (deltaX === 0), so native trackpad horizontal scrolling is untouched.
+ const handleWheel = useCallback((event: React.WheelEvent<HTMLDivElement>) => {
+ if (!event.shiftKey || event.deltaY === 0 || event.deltaX !== 0) {
+ return;
+ }
+ const el = scrollElRef.current;
+ if (!el) {
+ return;
+ }
+ // Nothing to scroll horizontally — let the event fall through so the page
+ // can scroll as it normally would.
+ if (el.scrollWidth <= el.clientWidth) {
+ return;
+ }
+ event.preventDefault();
+ el.scrollBy({left: event.deltaY, behavior: 'auto'});
+ }, []);
+
const scrollBy = useCallback((direction: -1 | 1) => {
const el = scrollElRef.current;
if (!el) {
@@ -346,6 +372,7 @@ export function Carousel({
<div
ref={composedRef}
tabIndex={0}
+ onWheel={handleWheel}
{...stylex.props(
styles.scroller,
gapStyles[gap],