feat: implement Toolbar component by k0ndee · Pull Request #5043 · callstack/react-native-paper

k0ndee · 2026-08-11T08:21:38Z

Motivation

Introduce a new Toolbar component implementing the Material Design 3 toolbars spec. Reuse theme tokens (shape, color roles, elevation) and follow the same component-tokens pattern as FAB / Checkbox.

Spec re-check (M3 toolbars)

Re-checked the M3 toolbars specs:

Two variants: floating (self-positioned pill, corner.full, elevation level 3) and docked (full-width bar pinned to the bottom edge, corner.none, no elevation, extends into safe-area insets).
floating supports horizontal/vertical orientation; docked is always horizontal per spec.
Default (standard) colors: container/unselected-button surfaceContainer, icon/label onSurfaceVariant, selected button secondaryContainer with onSecondaryFixedVariant (light) / onSecondaryContainer (dark) icon.
vibrant colorScheme: container/unselected-button primaryContainer, icon/label onPrimaryFixedVariant (light) / onPrimaryContainer (dark), selected button falls back to surfaceContainer with onSurface icon.
Direct IconButton/Button children are auto-recolored to match colorScheme unless they already set their own color (a mode on either opts them out in favor of their own mode-based coloring).

Changes

`Toolbar` / tokens / utils

New src/components/Toolbar/{Toolbar.tsx,tokens.ts,utils.ts}: variant (floating/docked), orientation (horizontal/vertical, floating-only), colorScheme (standard/vibrant), containerColor override, style/contentContainerStyle, testID, aria-label, theme, ref
Container shape/elevation/spacing resolved from ToolbarTokens; docked extends into safe-area insets via margin outside Surface's box, keeping the 64dp icon band untouched
withToolbarChildColors auto-recolors mode-less IconButton/Button children per colorScheme, without touching children that already set their own color/mode
Exported from src/index.tsx

Example / docs / tests

Example screen (ToolbarExample.tsx) covering both variants, both orientations, both color schemes, over a scrollable list
Docs page + prop table + theme colors table; screenshots for floating (horizontal/vertical) and docked, each in standard/vibrant
Unit tests (Toolbar.test.tsx) covering shape/elevation per variant, color resolution across light/dark themes for both color schemes, and child auto-recoloring behavior

Scope note

Per Satyajit Sahoo's recommendation, this implementation is split into a series of PRs for easier review, rather than landing as one large change. This PR is PR 1 of the series:

PR 1 (this PR) — Floating + docked variant, static (without animation, no FAB pairing), colorScheme standard/vibrant. Component, tokens, tests, docs, example.
PR 2 — Show/hide animation (offscreen slide + spring), generic scroll shared-value primitive.
PR 3 — FAB pairing, FAB/key-action collapse on scroll.
PR 4 — Trailing-edge overflow menu.

Related issue

Related to #4988

Test plan

yarn typecheck / yarn lint / Toolbar unit tests
Full unit test suite green
Manually verified in the example app: floating (horizontal/vertical) and docked, standard/vibrant, over scrolling content, light and dark themes

Visual verification

	standard	vibrant
floating, horizontal
floating, vertical
docked

Docs screenshots: docs/public/screenshots/toolbar_*.png.

MikitasK

nice work! 👍 overall, this looks like a solid foundation for the new Toolbar components
just a few points to address before merge:

MikitasK · 2026-08-11T17:08:57Z

+const standardColors = {
+  container: { light: 'surfaceContainer', dark: 'surfaceContainer' },
+  buttonContainer: { light: 'surfaceContainer', dark: 'surfaceContainer' },
+  selectedButtonContainer: {
+    light: 'secondaryContainer',
+    dark: 'secondaryContainer',
+  },
+  icon: { light: 'onSurfaceVariant', dark: 'onSurfaceVariant' },
+  selectedIcon: {
+    light: 'onSecondaryFixedVariant',
+    dark: 'onSecondaryContainer',
+  },
+  label: { light: 'onSurfaceVariant', dark: 'onSurfaceVariant' },
+} as const satisfies Record<string, ToneRole>;
+
+const vibrantColors = {
+  container: { light: 'primaryContainer', dark: 'primaryContainer' },
+  buttonContainer: { light: 'primaryContainer', dark: 'primaryContainer' },
+  selectedButtonContainer: {
+    light: 'surfaceContainer',
+    dark: 'surfaceContainer',
+  },
+  icon: { light: 'onPrimaryFixedVariant', dark: 'onPrimaryContainer' },
+  selectedIcon: { light: 'onSurface', dark: 'onSurface' },
+  label: { light: 'onPrimaryFixedVariant', dark: 'onPrimaryContainer' },
+} as const satisfies Record<string, ToneRole>;


could we use color roles from M3 spec directly?
standard buttons should use primary, selected buttons should use onSecondaryContainer, vibrant buttons should use onPrimaryContainer.
using FixedVariant roles may also produce incorrect colors with custom themes

Suggested change

const standardColors = {

container: { light: 'surfaceContainer', dark: 'surfaceContainer' },

buttonContainer: { light: 'surfaceContainer', dark: 'surfaceContainer' },

selectedButtonContainer: {

light: 'secondaryContainer',

dark: 'secondaryContainer',

},

icon: { light: 'onSurfaceVariant', dark: 'onSurfaceVariant' },

selectedIcon: {

light: 'onSecondaryFixedVariant',

dark: 'onSecondaryContainer',

},

label: { light: 'onSurfaceVariant', dark: 'onSurfaceVariant' },

} as const satisfies Record<string, ToneRole>;

const vibrantColors = {

container: { light: 'primaryContainer', dark: 'primaryContainer' },

buttonContainer: { light: 'primaryContainer', dark: 'primaryContainer' },

selectedButtonContainer: {

light: 'surfaceContainer',

dark: 'surfaceContainer',

},

icon: { light: 'onPrimaryFixedVariant', dark: 'onPrimaryContainer' },

selectedIcon: { light: 'onSurface', dark: 'onSurface' },

label: { light: 'onPrimaryFixedVariant', dark: 'onPrimaryContainer' },

} as const satisfies Record<string, ToneRole>;

const standardColors = {

container: { light: 'surfaceContainer', dark: 'surfaceContainer' },

buttonContainer: { light: 'surfaceContainer', dark: 'surfaceContainer' },

selectedButtonContainer: {

light: 'secondaryContainer',

dark: 'secondaryContainer',

},

icon: { light: 'primary', dark: 'primary' },

selectedIcon: {

light: 'onSecondaryContainer',

dark: 'onSecondaryContainer',

},

label: { light: 'primary', dark: 'primary' },

} as const satisfies Record<string, ToneRole>;

const vibrantColors = {

container: { light: 'primaryContainer', dark: 'primaryContainer' },

buttonContainer: { light: 'primaryContainer', dark: 'primaryContainer' },

selectedButtonContainer: {

light: 'surfaceContainer',

dark: 'surfaceContainer',

},

icon: { light: 'onPrimaryContainer', dark: 'onPrimaryContainer' },

selectedIcon: { light: 'onSurface', dark: 'onSurface' },

label: { light: 'onPrimaryContainer', dark: 'onPrimaryContainer' },

} as const satisfies Record<string, ToneRole>;

The spec for Toolbar tells that the standard colors should be:
icon: { light: 'onSurfaceVariant', dark: 'onSurfaceVariant' },
label: { light: 'onSurfaceVariant', dark: 'onSurfaceVariant' },

The vibrant colors according to spec are:
icon: { light: 'onPrimaryContainer', dark: 'onPrimaryContainer' },
label: { light: 'onPrimaryContainer', dark: 'onPrimaryContainer' },

I was confused about this, because these colors, like You commented are not the primary colors for Buttons and IconButtons according to the current spec for Buttons, but the Toolbar has it's own spec for included actions, that is why I used these tokens.

Now that the fixedVariants are removed, I can see that the light and dark are using the same roles for colors. I am thinking that I should remove the light and dark fields.

you’re right, thanks for clarifying 🙏 toolbar-specific spec uses onSurfaceVariant for standard actions & onPrimaryContainer for vibrant actions. removing light and dark fields totally makes sense - these semantic roles already adapt to the theme 👌

MikitasK · 2026-08-11T17:13:35Z

+        colorScheme,
+        selected: child.props.selected ?? false,
+      });
+      return React.cloneElement(child, { iconColor, containerColor });


what about selected & disabled icon buttons? explicit containerColor prevents IconButton from applying its normal disabled container treatment. could we use tonal mode for selected buttons?

Suggested change

return React.cloneElement(child, { iconColor, containerColor });

return React.cloneElement(child, {

iconColor,

containerColor,

...(child.props.selected ? { mode: 'contained-tonal' } : null),

});

That's a good catch. Fixed it in 6a695d7

MikitasK · 2026-08-11T17:21:54Z

+      // jumps position (e.g. bottom-center to a vertical trailing edge),
+      // avoiding a stale shadow "ghost" that `Surface`'s iOS shadow can
+      // leave at the old frame when an existing view is resized in place.
+      key={isVertical ? 'vertical' : 'horizontal'}


could we avoid changing key? any other options?
this approach implies that toolbar & its children remounts when orientation changes. it might cause loosing of child state & focus

Without remount, when switching from floating vertical to horizontal on iOS there is this bug that the inner Animated.View of SurfaceIOS inflated. See screenshots below:

I can't figure out why that is happening. On the first mount of floating horizontal Toolbar it looks fine, but when I switch between orientation that inflated pill is appearing. I will do some more debugging and try to find a more sutiable solution for that.

maybe we can extract pill background into a separate component & key only that component by orientation while keeping the toolbar content outside it?
I suppose, this should reset SurfaceIOS without remounting the buttons & losing their state or focus

<View style={pillStyle}> <PillBackground key={isVertical ? 'vertical' : 'horizontal'} elevation={elevation} /> <View role="toolbar" style={contentStyle}> {children} </View> </View>

I found a better solution. I moved the height and width control to the inner View inside Surface. Surface requires children prop so I would have to pass a {null}, which is I think is not an elegant approach here. With the latest commit I uploaded we keep the same code structure, where Surface wraps the inner View.

<Surface ref={isDocked ? undefined : ref} elevation={elevation} style={[ { backgroundColor, borderRadius, }, isDocked && styles.dockedFill, styles.content, !isDocked && style, ]} testID={testID} > <View role="toolbar" aria-label={ariaLabel} testID={`${testID}-content`} style={[ styles.content, isVertical ? styles.column : styles.row, { ...contentPadding, gap }, dockedInsetMargin, // Cross-axis thickness is the spec default (see `thickness` // above). Deliberately set here rather than on `Surface` (which // wraps this `View` with no size of its own, so it just hugs // it) — giving `Surface` an explicit width/height that flips // between renders is what previously left a stale shadow // "ghost" on iOS when `floating`'s `orientation` changed axis; // that no longer happens with the fixed dimension living here // instead. isDocked && { height: thickness }, !isDocked && (isVertical ? { width: thickness } : { height: thickness }), contentContainerStyle, ]} > {withToolbarChildColors({ children, theme, colorScheme })} </View> </Surface>

MikitasK

LGTM 👍

k0ndee added 4 commits August 10, 2026 15:08

feat: implement Toolbar component

161adbe

docs: add screenshots and adjust example screen for Toolbar

21d5f0b

docs: adjust Toolbar description

f0b3910

fix: enable style override for floating toolbar

3b06c16

k0ndee changed the title ~~@k0ndee/toolbar~~ feat: implement Toolbar component Aug 11, 2026

MikitasK reviewed Aug 11, 2026

View reviewed changes

k0ndee added 3 commits August 12, 2026 13:29

fix: adjust color tokens

019a38d

fix: fix coloring of selected & disabled icon button

6a695d7

fix: remove remounting Surface on orientation change

e5cfa88

MikitasK approved these changes Aug 13, 2026

View reviewed changes

Navigation Menu

Uh oh!

Uh oh!

feat: implement Toolbar component - #5043

feat: implement Toolbar component#5043
k0ndee wants to merge 7 commits into
callstack:mainfrom
k0ndee:@k0ndee/toolbar

k0ndee commented Aug 11, 2026

Uh oh!

MikitasK left a comment

Uh oh!

MikitasK Aug 11, 2026

Uh oh!

k0ndee Aug 12, 2026

Uh oh!

MikitasK Aug 12, 2026

Uh oh!

MikitasK Aug 11, 2026

Uh oh!

k0ndee Aug 13, 2026

Uh oh!

MikitasK Aug 11, 2026

Uh oh!

k0ndee Aug 12, 2026

Uh oh!

MikitasK Aug 12, 2026

Uh oh!

k0ndee Aug 13, 2026

Uh oh!

MikitasK left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

k0ndee commented Aug 11, 2026

Motivation

Spec re-check (M3 toolbars)

Changes

Toolbar / tokens / utils

Example / docs / tests

Scope note

Related issue

Test plan

Visual verification

Uh oh!

MikitasK 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!

MikitasK left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

`Toolbar` / tokens / utils