feat: TabsScrollArea + TabsScrollAreaIndicator by adrienzheng-cb · Pull Request #586 · coinbase/cds

adrienzheng-cb · 2026-04-03T20:50:36Z

What changed? Why?

Summary

⭐️⭐️⭐️ This change fully bridges the gap between Tabs and TabNavigation. ⭐️⭐️⭐️
Introduces TabsScrollArea on web and mobile as the supported way to host a horizontally scrolling Tabs row when content overflows. The API uses a render prop (children as a function) so consumers pass onActiveTabElementChange into Tabs for scroll-into-view behavior. Alpha TabbedChips is updated to compose TabsScrollArea so chip filters get the same overflow behavior and shared styling hooks.

Web (`packages/web`)

TabsScrollArea
- Root is an HStack; root props are based on BoxBaseProps (and related types) so layout props (e.g. width, maxWidth) can be set on the component without an extra wrapper.
- Render prop receives onActiveTabElementChange for wiring to Tabs.
- Default overflow UI via TabsScrollAreaOverflowIndicator (fade gradient + chevron controls).
- Supports compact on TabsScrollArea for smaller default overflow **IconButton**s (used when TabbedChips passes compact through).
- Optional OverflowIndicatorComponent to replace the default indicator; styles / classNames slots for root, scroll container, and overflow subparts.
TabbedChips (alpha)
- Wraps the tab row in TabsScrollArea; maps styles / classNames into TabsScrollArea slots (including deprecated styles.paddle merged into overflow button styles where applicable for backward compatibility).
Exports
- tabs/index.ts exports TabsScrollArea / overflow indicator types as needed.
componentConfig
- Registers TabsScrollArea for theme/config overrides.

Mobile (`packages/mobile`)

TabsScrollArea
- Horizontal ScrollView for the tab row; root layout uses HStack (or equivalent stack) with **BoxBaseProps-style props for dimensions on the root.
- TabsScrollAreaOverflowIndicator implemented with OverflowGradient and an explicit direction ('left' | 'right') API aligned with web semantics.
- OverflowGradient updated to support the pinning/gradient direction needed for left/right edges.
- Invalid children: if children is not a function, the component does not throw; it renders non-function children (or nothing) so misuse fails softly (scroll-into-view wiring is skipped in that case).
TabbedChips (alpha)
- Composes TabsScrollArea and passes through overflow-related styles.
Exports & componentConfig
- Same pattern as web: public exports and TabsScrollArea entry in componentConfig.

Documentation (`apps/docs`)

New component doc: components/navigation/TabsScrollArea/
- index.mdx, web/mobile examples, props tables, styles tables, webMetadata.json / mobileMetadata.json (short descriptions, related components such as Tabs / TabbedChips where applicable).
- Examples use width / maxWidth on TabsScrollArea instead of an extra Box wrapper where appropriate.
docgen.config.js
- Includes tabs/TabsScrollArea for API extraction.
sidebars.ts
- Navigation entry for TabsScrollArea next to Tabs.
Tabs docs
- Scrolling with TabsScrollArea sections (web + mobile examples) and metadata tweaks (related components, etc.).

Apps

apps/mobile-app
- Routes updated so the in-app catalog includes TabsScrollArea where other navigation components are registered.

UI changes

storybook
docs

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2026-04-03.at.17.02.27.mov

Screen.Recording.2026-04-03.at.5.03.14.PM.mov

Testing

How has it been tested?

Testing instructions

Illustrations/Icons Checklist

Required if this PR changes files under packages/illustrations/** or packages/icons/**

verified visreg changes with Terran (include link to visreg run/approval)
all illustration/icons names have been reviewed by Dom and/or Terran

Change management

type=routine
risk=low
impact=sev5

automerge=false

cb-heimdall · 2026-04-03T20:50:42Z

🟡 Heimdall Review Status

Requirement Status More Info

Reviews

🟡 0/1

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 1

Global minimum 0

Max 1

1

1 if commit is unverified 0

Sum 1

CODEOWNERS 🟡 See below

🟡 `CODEOWNERS`

Code Owner Status Calculation

ui-systems-eng-team

🟡 0/1

Denominator calculation

Additional CODEOWNERS Requirement

Show calculation

Sum	0

0

From CODEOWNERS 1

Sum 1

github-actions · 2026-04-03T21:31:55Z

https://percy.io/d424b72f/web/cds-mobile-visreg-03c97426/builds/48502793

cb-ekuersch

I see the scrolling functionality was removed from TabbedChips but I guess the main thing im thinking is why? Also isn't NavigationTabs deprecated? I saw it mentioned in the PR description as being a motivating reason for these changes

cb-ekuersch · 2026-04-03T23:08:41Z

packages/mobile/src/tabs/TabsScrollArea.tsx

+  onActiveTabElementChange: (element: View | null) => void;
+};
+
+export type TabsScrollAreaBaseProps = Omit<BoxBaseProps, 'children' | 'ref'> &


dang we should probably remove 'children' from BoxBaseProps at some point

cb-ekuersch · 2026-04-03T23:09:13Z

packages/mobile/src/tabs/TabsScrollArea.tsx

+     * Render function that receives `onActiveTabElementChange` (wire to `Tabs` as
+     * `onActiveTabElementChange`).
+     */
+    children: (props: TabsScrollAreaRenderProps) => React.ReactNode;


children should go on Props not BaseProps - @hcopp wdyt? I recall us coming to that conclusion the other day

moved children to full props

cb-ekuersch · 2026-04-03T23:09:31Z

packages/mobile/src/tabs/TabsScrollArea.tsx

+  };
+
+export type TabsScrollAreaProps = TabsScrollAreaBaseProps & {
+  styles?: {


use the styles/classNAmes helper type

we should make an internal lint rule to enforce this

I will add lint rule in a separate pr

cb-ekuersch · 2026-04-03T23:10:55Z

packages/mobile/src/tabs/TabsScrollArea.tsx

+};
+
+const TabsScrollAreaWithRef = forwardRef<View, TabsScrollAreaProps>(
+  function TabsScrollArea(_props, ref) {


just curious, why can't this be a feature of Tabs, enabled by certain props? Having a separate component feels a bit heavy just to support scrolling with some opinionated overflow styles

I thought about doing it that way and it would be very ideal. however:

Tabs component is a root div wrapping a list of tab, we cannot add additional paddle/overflow indicator inside the root div because the div has a role of "tablist" and having buttons inside makes it inaccessible

we don't want to add additional layers outside of the current root of Tabs because Tabs are already used by consumers and that can lead to drastic behavioral changes and may break their styling if they applies complex custom styles.. We also want to avoid wrapping the component in additional layer based on a scrollable prop conditionally

Tabs component is a root div wrapping a list of tab, we cannot add additional paddle/overflow indicator inside the root div because the div has a role of "tablist" and having buttons inside makes it inaccessible

So do customers use either Tabs or TabScrollArea depending on if they want scroll behavior?

Re: Tabs not rendering TabsScrollArea - why can't TabsScrollArea implement tablist role itself and then in Tabs if it decides it needs to render TabsScrollArea it doesn't apply the role to it's own container?

TabsScrollArea is just an add-on to Tabs. It does not render the Tabs itself, it is just a scrollable Box that detects horizontal overflow and displays overflow indicators when overflow happens.

We didn't build this behavior into Tabs because Tabs are currently being used by consumers, and we want to avoid breaking their existing usages. One solution to that is to add an optional scrollable prop to Tabs that only add the overflow detection to it if enabled. However, Tabs' DOM structure becomes inconsistent when the prop is turned on/off if we go with that route. In the past we had issues which components that adds additional layer of Pressable around itself based on availability of certain props. (eg Cell) and we have been trying to avoid that pattern since.

Hence, I decided to keep TabsScrollArea as a separate component and leave Tabs as it is (a primitive component that only takes care of the business logic).

This way, existing usages of Tabs in consumer repos are unaffected by this change. They probably have implemented their own overflow strategy if they needed it. Anyone who are still using the Deprecated TabNavigation or would like to add scroll support to Tabs can switch to the following

<TabsScrollArea> { ({ onActiveTabElementChange }) => <Tabs onActiveTabElementChange={onActiveTabElementChange} {...otherProps} /> } </TabsScrollArea>

cb-ekuersch · 2026-04-03T23:11:21Z

packages/web/src/tabs/TabsScrollArea.tsx

+  style?: React.CSSProperties;
+  /** Merged with the root `HStack`. */
+  className?: string;
+  styles?: {


use style and classNames type helper

adrienzheng-cb · 2026-04-03T23:39:51Z

I see the scrolling functionality was removed from TabbedChips but I guess the main thing im thinking is why? Also isn't NavigationTabs deprecated? I saw it mentioned in the PR description as being a motivating reason for these changes

cc:@cb-ekuersch We didn't remove it we just replaced the old scrolling implementation inside TabbedChips with the new TabsScrollArea. TabsScrollArea is essentially the old scroll logic from TabbedChips and TabNavigation extracted into its own component.

We did deprecate TabNavigation, however, Tabs (supposedly the replacement) was too primitive to provide the same functionalities TabNavigation used to offer and TabNavigation was heavily used. We had consumers complaining that it was hard to migrate to Tabs because it didn't have Tab, ActiveIndicator, or scroll indicators built in. I recently added DefaultTab and DefaultTabsActiveIndicator in a previous pr, and this pr is the last piece of puzzle for TabNavigation users to easily migrate to Tabs.

feat: TabsScrollArea + TabsScrollAreaIndicator

2d78efd

adrienzheng-cb had a problem deploying to production April 3, 2026 20:50 — with GitHub Actions Error

github-actions bot added packages:web packages:mobile apps:docs apps:mobile-app labels Apr 3, 2026

adrienzheng-cb had a problem deploying to production April 3, 2026 20:51 — with GitHub Actions Error

fix tests

1a6aada

adrienzheng-cb temporarily deployed to production April 3, 2026 20:52 — with GitHub Actions Inactive

adrienzheng-cb had a problem deploying to production April 3, 2026 20:52 — with GitHub Actions Failure

adrienzheng-cb requested review from hcopp and maximo-macchi-cb April 3, 2026 21:03

lint

f019f17

adrienzheng-cb had a problem deploying to production April 3, 2026 21:16 — with GitHub Actions Error

adrienzheng-cb temporarily deployed to production April 3, 2026 21:16 — with GitHub Actions Inactive

adrienzheng-cb added 2 commits April 3, 2026 17:33

update docs

1fff7be

update mobile examples

096e8e6

adrienzheng-cb temporarily deployed to production April 3, 2026 21:35 — with GitHub Actions Inactive

cb-ekuersch reviewed Apr 3, 2026

View reviewed changes

Update props and styles definition

507c6d5

adrienzheng-cb temporarily deployed to production April 7, 2026 15:30 — with GitHub Actions Inactive

adrienzheng-cb temporarily deployed to production April 7, 2026 15:31 — with GitHub Actions Inactive

Conversation

adrienzheng-cb commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed? Why?

Summary

Web (packages/web)

Mobile (packages/mobile)

Documentation (apps/docs)

Apps

UI changes

Testing

How has it been tested?

Testing instructions

Illustrations/Icons Checklist

Change management

Uh oh!

cb-heimdall commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟡 Heimdall Review Status

🟡 CODEOWNERS

Uh oh!

github-actions bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cb-ekuersch 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!

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!

adrienzheng-cb Apr 7, 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!

adrienzheng-cb commented Apr 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

adrienzheng-cb commented Apr 3, 2026 •

edited

Loading

Web (`packages/web`)

Mobile (`packages/mobile`)

Documentation (`apps/docs`)

cb-heimdall commented Apr 3, 2026 •

edited

Loading

🟡 `CODEOWNERS`

github-actions bot commented Apr 3, 2026 •

edited

Loading

adrienzheng-cb Apr 7, 2026 •

edited

Loading