feat(menu): modernize Menu to Material Design 3 specs by matkoson · Pull Request #5037 · callstack/react-native-paper

matkoson · 2026-07-23T10:56:02Z

Motivation

Modernize Menu / Menu.Item to the latest Material Design 3 specs. Reuse theme tokens (shape, typography, motion, color roles) and extract component tokens in the same pattern as Checkbox / FAB / ConnectedButtonGroup.

Spec re-check (M3 menus)

Re-checked M3 menus specs and overview:

Container shape corner.large; item first/last/selected corner.medium.
Label labelLarge; supporting bodySmall; trailing supporting labelLarge.
Default container fill is MD3 surfaceContainerLow. The elevation prop controls shadow only (Paper’s elevation.level2 maps to different surfaceContainer tones, so it is not used as the menu fill).
Selected items use tertiaryContainer / onTertiaryContainer.
Expressive choices: optional colorScheme="vibrant"; spring-animated item corner morph as focus/selection moves; optional badge and lightweight submenu portal surface; Menu.Section group gaps (8dp) in addition to Divider.

Changes

Tokens / Menu / Menu.Item

Container fill surfaceContainerLow; surface corner.large; first/last/selected item corner.medium via layout context (no cloneElement / no displayName filtering)
labelLarge, supporting + trailing supporting text, selected colors (disabled wins with content opacity)
Spring open/close via toRawSpring + reduce-motion snap
colorScheme standard | vibrant
Menu.Section group gaps; badge; lightweight submenu portal; Animated.spring per-corner radius morph on focus/selection

Example / docs / tests

Example: selection, supporting, vibrant, sections, badge, submenu
Docs + theme colors tables for selected/vibrant roles; refreshed Android + iOS screenshots
Unit tests for shape, colors, supporting text, dense, motion/reduce-motion, badge, submenu

Related issue

Fixes #4977

Test plan

yarn typecheck / yarn lint / Menu unit tests
Full unit test suite green
Android visual matrix (Pixel 9 Pro XL emulator)
iOS visual matrix (iPhone 16 Pro simulator)

Visual verification

Platform	closed	icons + disabled	selected + supporting	vibrant	bottom anchor
Android (Pixel 9 Pro XL)
iOS (iPhone 16 Pro)

Docs screenshots: docs/public/screenshots/menu-*.png and menu-ios-*.png.

Menu.Item used fixed 48dp height with two-line supporting text and a content minWidth that collapsed trailingSupportingText to zero width. Use minHeight + padding for supporting rows, intrinsic row sizing for trailing slots, and showcase the vibrant color scheme in the example.

MikitasK

great work on this modernization 👏
just a few suggestions to consider before merging the PR:

MikitasK · 2026-08-17T18:11:47Z

-  const { titleColor, iconColor, contentOpacity } = getMenuItemColor({
+  const layout = useMenuItemLayout();
+
+  const colorScheme = colorSchemeProp ?? layout?.colorScheme ?? 'standard';


what about using MenuRootContext as a fallback here?
I suppose, items rendered through wrapper / Fragment won't receive MenuItemLayoutContext & will fall back to standard scheme even inside vibrant menu

Suggested change

const colorScheme = colorSchemeProp ?? layout?.colorScheme ?? 'standard';

const root = useMenuRoot();

const colorScheme = colorSchemeProp ?? layout?.colorScheme ?? root?.colorScheme ?? 'standard';

MikitasK · 2026-08-17T18:21:56Z

          >
            {title}
          </Text>
+          {supportingText ? (


could use explicit presence check for supportingText & trailingSupportingText?
this way values like supportingText={0} will be rendered

instead, we can define such variable:

const hasSupportingText = supportingText != null && typeof supportingText !== 'boolean';

and then use it here

Suggested change

{supportingText ? (

{hasSupportingText ? (

MikitasK · 2026-08-17T18:22:35Z

+            </Text>
+          ) : null}
        </View>
+        {trailingSupportingText ? (


same suggestion here

MikitasK · 2026-08-17T18:35:12Z

+          ...(supportingText
+            ? { paddingVertical: 8 }
+            : { height: dense ? denseItemHeight : itemHeight }),


could we allow the item to grow when trailing supporting text is present?
it currently keeps fixed 48/32dp height & might be clipped with large accessibility font sizes

we can define the following vars first:

const hasSupportingText = supportingText != null && typeof supportingText !== 'boolean'; const hasTrailingSupportingText = trailingSupportingText != null && typeof trailingSupportingText !== 'boolean';

and then use it like that:

Suggested change

...(supportingText

? { paddingVertical: 8 }

: { height: dense ? denseItemHeight : itemHeight }),

...(hasSupportingText || hasTrailingSupportingText

? { paddingVertical: 8 }

: { height: dense ? denseItemHeight : itemHeight }),

MikitasK · 2026-08-17T18:41:29Z

+  const contentMaxWidth = getContentMaxWidth({
+    iconWidth: iconSize,
    leadingIcon,
    trailingIcon,
+    hasTrailingSupportingText: Boolean(trailingSupportingText),
  });


could we use explicit presence flags for these props?
this approach should keep numeric values (such as 0), but ignore boolean placeholders

Suggested change

const contentMaxWidth = getContentMaxWidth({

iconWidth: iconSize,

leadingIcon,

trailingIcon,

hasTrailingSupportingText: Boolean(trailingSupportingText),

});

const hasTrailingSupportingText = trailingSupportingText != null && typeof trailingSupportingText !== 'boolean';

const contentMaxWidth = getContentMaxWidth({

iconWidth: iconSize,

leadingIcon,

trailingIcon,

hasTrailingSupportingText,

});

mikolajadamowicz · 2026-08-25T10:55:11Z

Hey @MikitasK i've took over the PR and fixed your comments here: #5073

JKobrynski · 2026-08-25T11:18:01Z

@@ -0,0 +1,86 @@
+import { Animated } from 'react-native';


Please use Reanimated

JKobrynski · 2026-08-25T13:20:45Z

+ */
+export function countMenuItems(children: React.ReactNode): number {
+  let count = 0;
+  React.Children.forEach(children, (child) => {


Drop the React.Children walk — it's one of the three things v6 exists to remove (#4954). #5018 and #5076 both replace the same pattern with context plus typed props.

JKobrynski · 2026-08-25T13:21:30Z

+
+const shapes = {
+  /** Menu surface corner. Spec: corner.large (16dp). */
+  container: 'large' as ShapeToken,


Try not to use as casts

JKobrynski · 2026-08-25T13:22:08Z

+        opacityAnimation: opacityAnimationRef.current,
+        menuWidth: menuLayoutResult.width,
+        menuHeight: menuLayoutResult.height,
+        theme: theme as Theme,


Try not to use as casts

JKobrynski · 2026-08-25T13:23:17Z

  row: {
    flexDirection: 'row',
+    alignItems: 'center',
+    alignSelf: 'flex-start',


alignSelf: 'flex-start' shrink-wraps the row, so the trailing shortcut sits next to the label instead of at the item's trailing edge — visible in menu-2.png. Drop it and give content flexGrow: 1.

JKobrynski · 2026-08-25T13:23:55Z

      aria-disabled={disabled}
      aria-checked={ariaChecked}
-      aria-selected={ariaSelected}
+      aria-selected={ariaSelected ?? (isSelected ? true : undefined)}


aria-selected isn't valid on role="menuitem", so on web a selected item announces the same as an unselected one. Use menuitemradio / menuitemcheckbox with aria-checked.

JKobrynski · 2026-08-25T13:24:47Z

+// Must run before any React Native modules load. RN Animated only force-updates
+// host styles under Jest when NODE_ENV === 'test'; otherwise setValue/timing
+// go through setNativeProps, which does not update props visible to toHaveStyle.
+process.env.NODE_ENV = 'test';


Jest already sets NODE_ENV=test when it's unset (jest-cli/bin/jest.js) and nothing in this repo overrides it, so this file is a no-op. Remove it and the setupFiles entry.

JKobrynski · 2026-08-25T13:25:24Z

  ## Theme colors

-  <ThemeColorsTable themeColorsData={{"-":{"backgroundColor":"theme.colors.elevation.level2"}}} componentName="Menu" />
+  <ThemeColorsTable themeColorsData={{"standard":{"backgroundColor":"theme.colors.surfaceContainerLow"},"vibrant":{"backgroundColor":"theme.colors.tertiaryContainer"},"selected item":{"backgroundColor":"theme.colors.tertiaryContainer","textColor":"theme.colors.onTertiaryContainer"}}} componentName="Menu" />


This page is generated with componentName="Menu", so FAB.Menu now claims a surfaceContainerLow fill and a vibrant tertiaryContainer variant it doesn't have, and shows Menu's screenshots.

mikolajadamowicz · 2026-08-27T08:39:21Z

@JKobrynski i have updated my PR #5073 to fix bugs from your comments. I think we can close this one and continue review on #5073 -> it preserves the git history of this PR, is rebased onto the newest main and has commits with comments fixes

JKobrynski · 2026-08-27T08:45:54Z

@mikolajadamowicz closing this one

matkoson added 10 commits July 21, 2026 11:58

feat(menu): modernize Menu to Material Design 3 specs

966c6e9

fix(menu): make Animated.spring and Jest host styles work

8c5a431

docs(menu): ship MD3 screenshots and tighten Menu tests

648eae4

feat(menu): section gaps, badge, submenu, context layout, shape morph

4574dde

docs(menu): add iOS Menu visual matrix screenshots

2b22d34

docs(menu): refresh cross-platform Menu visual matrix

17d40fe

fix(menu): align container fill, morph animation, docs, and tests

797dd14

docs(menu): regenerate PropTables and MD3 usage examples

a56bf2d

chore: self-review

b4ff449

MikitasK reviewed Aug 17, 2026

View reviewed changes

mikolajadamowicz mentioned this pull request Aug 25, 2026

feat(menu): modernize Menu to Material Design 3 specs #5073

Open

5 tasks

JKobrynski requested changes Aug 25, 2026

View reviewed changes

JKobrynski closed this Aug 27, 2026

	const colorScheme = colorSchemeProp ?? layout?.colorScheme ?? 'standard';
	const root = useMenuRoot();
	const colorScheme = colorSchemeProp ?? layout?.colorScheme ?? root?.colorScheme ?? 'standard';

Uh oh!

Uh oh!

Conversation

matkoson commented Jul 23, 2026

Motivation

Spec re-check (M3 menus)

Changes

Tokens / Menu / Menu.Item

Example / docs / tests

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!

MikitasK Aug 17, 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!

Choose a reason for hiding this comment

Uh oh!

mikolajadamowicz commented Aug 25, 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!

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!

mikolajadamowicz commented Aug 27, 2026

Uh oh!

JKobrynski commented Aug 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MikitasK Aug 17, 2026 •

edited

Loading