[IRN-6718] [BpkCardListCarousel] Add physical page-based scrolling to desktop by grc-ong · Pull Request #4138 · Skyscanner/backpack

grc-ong · 2026-01-23T15:19:21Z

Summary

This PR adds native physical scrolling behavior to the BpkCardListCarousel component on desktop and tablet devices, replacing the previous button-only navigation with a more natural scrolling experience while maintaining the page-based navigation model.

Changes

Key improvements:

Physical page-based scrolling: Users can now scroll through cards using mouse wheel, trackpad, or touch
gestures on desktop/tablet, with scrolling snapping to pages rather than individual cards
Bidirectional synchronization: The carousel now properly syncs between programmatic scrolling
(pagination buttons) and user-initiated scrolling (wheel/touch), preventing conflicts between the two
Improved scroll lock mechanism: Replaced the previous scroll lock system with a more robust
usePageScrollSync hook that uses a silence-based lock release to distinguish between user and
programmatic scrolling

Technical changes:

Refactored scroll synchronization logic into a new usePageScrollSync hook in utils.tsx
Changed carousel container from overflow-x: hidden to overflow-x: scroll on desktop/tablet
Added .bpk-card-list-row-rail__card--page-start class to enable page-based scroll snapping (only first
card of each page snaps on desktop/tablet)
Removed scroll-snap-stop: always from all cards and applied it only to page-start cards on desktop/tablet
Mobile behavior unchanged - continues to use per-card scroll snapping
Removed the old useScrollToCard and lockScroll utility functions
Updated test snapshots and added comprehensive test coverage for the new scroll behavior

Testing

This has been manually tested on:

Desktop:

Chrome
Safari
Firefox

iPad:

Chrome
Safari

Android phone:

Chrome
Samsung

iPhone:

Chrome
Safari

Remember to include the following changes:

skyscanner-backpack-bot · 2026-01-23T15:28:07Z

	Warnings
⚠️	Package source files (e.g. `packages/package-name/src/Component.js`) were updated, but snapshots weren't. Have you checked that the tests still pass?

Browser support

If this is a visual change, make sure you've tested it in multiple browsers.

Generated by 🚫 dangerJS against 7926a96

skyscanner-backpack-bot · 2026-01-23T15:57:29Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

skyscanner-backpack-bot · 2026-01-23T16:53:47Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

skyscanner-backpack-bot · 2026-01-26T16:20:52Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

grc-ong · 2026-01-27T22:52:52Z


    display: flex;
-    overflow-x: hidden;
+    overflow-x: scroll;


enables scroll

grc-ong · 2026-01-27T22:53:06Z

    // Negative margin to ensure box-shadow of content is not cut off
    margin-block: -(tokens.bpk-spacing-lg());
    margin-inline: -(tokens.bpk-spacing-md());
+    -webkit-overflow-scrolling: touch;


enables native scroll on safari

grc-ong · 2026-01-27T22:56:15Z


+      @include breakpoints.bpk-breakpoint-above-mobile {
+        // On tablet and desktop, only snap to page-start cards for page-based scrolling
+        scroll-snap-align: none;


this means not specifying where on the card to snap to so no snap scroll
because logic to snap every so cards will be determined elsewhere

grc-ong · 2026-01-27T22:59:27Z

+  &__card--page-start {
+    @include breakpoints.bpk-breakpoint-above-mobile {
+      scroll-snap-align: start;
+      scroll-snap-stop: always;


'always' makes it so it stops at the next card as opposed to 'normal', the same amount of force on the trackpad will scroll through more options

grc-ong · 2026-01-27T23:00:00Z


  const stateScrollingLockRef = useRef(false);
  const openSetStateLockTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const [lockVersion, setLockVersion] = useState(0);


state to share between page-based scrolling and the button navigation

…ng and button nav is a bit broken

skyscanner-backpack-bot · 2026-01-27T23:28:31Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

grc-ong · 2026-01-28T09:59:14Z

+  // Mobile: scroll to individual card (use currentIndex directly)
  useScrollToCard(
-    currentIndex * initiallyShownCards,
+    isMobile ? currentIndex : currentIndex * initiallyShownCards,


separating mobile experience that snaps to every card

grc-ong · 2026-01-28T09:59:41Z

    root,
    cardRefs,
    stateScrollingLockRef,
+    openSetStateLockTimeoutRef,


not sure what this is yet

skyscanner-backpack-bot · 2026-01-28T11:12:00Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

skyscanner-backpack-bot · 2026-01-28T12:47:37Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

Jimmy cook (jimmycook) · 2026-01-28T13:53:08Z

  useEffect(() => {
    const firstVisible = visibilityList.indexOf(1);
-    if (firstVisible >= 0) {
+    if (firstVisible >= 0 && stateScrollingLockRef.current) {


Only set the index from within our component if we're locked, meaning there has been a user scrolling interaction

Jimmy cook (jimmycook) · 2026-01-28T13:53:23Z

+
        const commonProps = {
-          className: getClassName(`bpk-card-list-row-rail__${layout}__card`),
+          className: `${getClassName(`bpk-card-list-row-rail__${layout}__card`)}${isPageStart ? ` ${getClassName('bpk-card-list-row-rail__card--page-start')}` : ''}`,


Add the page start classes to the correct cards

skyscanner-backpack-bot · 2026-02-05T19:10:29Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

skyscanner-backpack-bot · 2026-02-05T19:18:47Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

skyscanner-backpack-bot · 2026-02-05T21:54:56Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

Max Liefkes (chiefkes) · 2026-02-06T11:19:43Z

+  usePageScrollSync({
+    currentIndex,
+    setCurrentIndex,
+    initiallyShownCards,
    cardRefs,
-    stateScrollingLockRef,
-  );
+    visibilityList,
+    container: root,
+    enabled: !isMobile,
+  });


refactor various scroll related logic into a consolidated hook to make it easier to reason about and control the various scroll mechanisms

Max Liefkes (chiefkes) · 2026-02-06T11:20:17Z

-  useEffect(() => {
-    const container = root;
-    if (isMobile || !container) return undefined;
-
-    const lockScrollDuringInteraction = () => {
-      lockScroll(stateScrollingLockRef, openSetStateLockTimeoutRef);
-    };
-
-    container.addEventListener('wheel', lockScrollDuringInteraction);
-    container.addEventListener('touchmove', lockScrollDuringInteraction);
-
-    return () => {
-      container.removeEventListener('touchmove', lockScrollDuringInteraction);
-      container.removeEventListener('wheel', lockScrollDuringInteraction);
-      if (openSetStateLockTimeoutRef.current) {
-        clearTimeout(openSetStateLockTimeoutRef.current);
-      }
-    };
-  }, [root]);


This responsibility moved to new usePageScrollSync hook

Max Liefkes (chiefkes) · 2026-02-06T11:20:22Z

-  useEffect(() => {
-    const firstVisible = visibilityList.indexOf(1);
-    if (firstVisible >= 0) {
-      const newIndex = Math.floor(firstVisible / initiallyShownCards);
-      if (newIndex !== currentIndex) {
-        setCurrentIndex(newIndex);
-      }
-    }
-  }, [initiallyShownCards]);


This responsibility moved to new usePageScrollSync hook

Max Liefkes (chiefkes) · 2026-02-06T11:22:45Z

  });
 };

-export const useScrollToCard = (


This responsibility moved to new usePageScrollSync hook

skyscanner-backpack-bot · 2026-02-06T11:28:32Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

…ow-to-rail

skyscanner-backpack-bot · 2026-02-06T14:06:58Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

Jimmy cook (jimmycook) · 2026-02-06T14:40:22Z

-          className: getClassName(`bpk-card-list-row-rail__${layout}__card`),
+          className: getClassName(
+            `bpk-card-list-row-rail__${layout}__card`,
+            isPageStart && 'bpk-card-list-row-rail__card--page-start',


Page start to allow the scroll snapping styles 🚀

Jimmy cook (jimmycook) · 2026-02-06T14:41:00Z

+      container.getBoundingClientRect().bottom > 0 &&
+      container.getBoundingClientRect().bottom <= window.innerHeight;
+
+    if (!isVisible) {


early return if not visible to not scroll

Jimmy cook (jimmycook) · 2026-02-06T14:41:14Z

+    const targetCard = cardRefs.current?.[currentIndex * initiallyShownCards];
+    if (!targetCard) {
+      return;
+    }


early return if the target doesn't exist, sensible

Jimmy cook (jimmycook)

looks good from Irn Bru side

kerrie-wu · 2026-02-10T06:11:04Z


-export const RELEASE_LOCK_DELAY = 20;
-export const RENDER_BUFFER_SIZE = 3;
+export const RELEASE_LOCK_DELAY = 200;


Is 200ms derived from empirical testing across trackpad/wheel/iPad touch? Any risk of sluggish page indicator updates?

Hi - yes 200 was a sweetspot value that I arrived at after testing on multiple devices and browsers. At this value there is no flickering of the page index indicators (even on lower powered devices), and the page indicator updates feel natural and not at all sluggish

kerrie-wu · 2026-02-10T06:18:20Z

          cardDimensionStyle.height = `${firstCardHeightRef.current}px`;
        }

+        const isPageStart = index % initiallyShownCards === 0;


Minor thought: since page-start is calculated via index % initiallyShownCards, do we handle responsive changes and the “incomplete last page” case as expected? Might be worth a quick test just to make sure snapping always lands on a valid page start.

Good point! I've had a look at a storybook example with 13 cards. It appears to work as expected and handles responsive changes well too. When we move from index 9 to 12, card visibility goes from [9, 10, 11], to [10, 11, 12] which is intuitive behaviour. With page index still at 12 and responsively moving to mobile, visibility is snapped to [12] as expected

bpk-cardlist-responsive.webm

…ow-to-rail

skyscanner-backpack-bot · 2026-02-10T09:34:34Z

Visit https://backpack.github.io/storybook-prs/4138 to see this build running in a browser.

WIP: add physical page-based scrolling to desktop

12c0dab

move behaviour to classnames

f2a2f9d

add tests

b7f7f67

grc-ong added enhancement minor Non breaking change labels Jan 23, 2026

grc-ong changed the title ~~[IRN-6718] WIP: add physical page-based scrolling to desktop~~ [IRN-6718] [BpkCardListCarousel] Add physical page-based scrolling to desktop Jan 23, 2026

WIP

5eb0b40

grc-ong commented Jan 27, 2026

View reviewed changes

WIP: pagination dots don't jump anymore but updates slowly on scrolli…

3de69f7

…ng and button nav is a bit broken

grc-ong commented Jan 28, 2026

View reviewed changes

revert most of claudes changes for now

74a26e5

only set current index when locked

fc7d263

tests for lock behaviour

e21edf5

Jimmy cook (jimmycook) reviewed Jan 28, 2026

View reviewed changes

Jimmy cook (jimmycook) added 3 commits January 28, 2026 13:54

remove unused param

9417b6b

remove unused param

c6fff16

readd lock release

6600822

unit test improvements

75755ba

Max Liefkes (chiefkes) added 2 commits February 5, 2026 21:20

optimise

ba6b1bc

better differentiation of user input starting

daf4a87

Max Liefkes (chiefkes) added 3 commits February 5, 2026 22:22

simplify lock mechanism

4d8dd66

further simplify

fadbe54

tidy

8d042fa

Max Liefkes (chiefkes) marked this pull request as ready for review February 6, 2026 10:41

Max Liefkes (chiefkes) reviewed Feb 6, 2026

View reviewed changes

lint

809d702

Max Liefkes (chiefkes) reviewed Feb 6, 2026

View reviewed changes

Merge branch 'main' into IRN-6178-add-physical-scrolling-to-desktop-r…

fc26797

…ow-to-rail

Jimmy cook (jimmycook) reviewed Feb 6, 2026

View reviewed changes

Jimmy cook (jimmycook) approved these changes Feb 6, 2026

View reviewed changes

Alex (rabisse) approved these changes Feb 6, 2026

View reviewed changes

kerrie-wu reviewed Feb 10, 2026

View reviewed changes

Merge branch 'main' into IRN-6178-add-physical-scrolling-to-desktop-r…

7926a96

…ow-to-rail

kerrie-wu approved these changes Feb 10, 2026

View reviewed changes

kerrie-wu merged commit 61cb207 into main Feb 10, 2026
15 checks passed

kerrie-wu deleted the IRN-6178-add-physical-scrolling-to-desktop-row-to-rail branch February 10, 2026 10:17

Conversation

grc-ong commented Jan 23, 2026 • edited by chiefkes Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Key improvements:

Technical changes:

Testing

Uh oh!

skyscanner-backpack-bot Bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Browser support

Uh oh!

skyscanner-backpack-bot Bot commented Jan 23, 2026

Uh oh!

skyscanner-backpack-bot Bot commented Jan 23, 2026

Uh oh!

skyscanner-backpack-bot Bot commented Jan 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

grc-ong Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

skyscanner-backpack-bot Bot commented Jan 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

skyscanner-backpack-bot Bot commented Jan 28, 2026

Uh oh!

skyscanner-backpack-bot Bot commented Jan 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

skyscanner-backpack-bot Bot commented Feb 5, 2026

Uh oh!

skyscanner-backpack-bot Bot commented Feb 5, 2026

Uh oh!

skyscanner-backpack-bot Bot commented Feb 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

skyscanner-backpack-bot Bot commented Feb 6, 2026

Uh oh!

skyscanner-backpack-bot Bot commented Feb 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jimmy cook (jimmycook) left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

grc-ong commented Jan 23, 2026 •

edited by chiefkes

Loading

skyscanner-backpack-bot Bot commented Jan 23, 2026 •

edited

Loading

grc-ong Jan 27, 2026 •

edited

Loading