fix(fab): align MD3 variants and interaction states by likevy · Pull Request #5110 · callstack/react-native-paper

likevy · 2026-09-08T07:16:30Z

Motivation

FAB presets didn't use MD3 role names and hover elevation was unused.

Breaking: tonalPrimary is now primaryContainer, same for secondary and tertiary.
On web, all FAB types rise from level 3 to 4 on hover. React Native 0.85 sends no hover events on iOS or Android by default.
A hidden FAB can't be focused or pressed, and screen readers skip it. On web, hiding a keyboard-focused FAB returns focus to the previous element.

Related issue

FAB review checklist.

Screenshots / Videos

Test plan

In the FAB example:

Cycle the Color chips.
On web, hover each FAB type: the shadow rises, pressing lowers it.
Turn off Show FAB: Tab and screen readers skip it.
Both icon-only FABs announce "Compose".

JKobrynski · 2026-09-14T13:06:04Z

We've got conflicts @likevy

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

satya164

Review by Claude

The PR description no longer matches the code. It still says surface is added, hover elevation is web only, the menu trigger does not rise, and an explicit shell elevation is kept. The second commit changed all four. Please update it so the description matches what ships. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T16:57:20Z

+  // Branded artwork has no prescribed icon color; onSurface is a fallback.
+  branded: { container: 'surfaceContainerHigh', content: 'onSurface' },


The earlier question about whether branded is in the official guidelines has no answer yet, and the variant is still here. branded comes from material-web's md-branded-fab, which is meant for multicolor brand logos and has no icon color token, so onSurface here is a guess.

It also costs API surface. FAB.Menu needs a separate MenuVariant type to exclude it, and the example needs a chip filter, a reset on type switch and a ternary at the trigger. I suggest you remove branded and MenuVariant. Apps that want this look can pass containerColor={colors.surfaceContainerHigh}. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T16:57:20Z

+If you omit `variant`, no change is needed. Replace `variant="surface"` with
+one of the supported color variants, such as `primaryContainer`.


primaryContainer does not keep the v5 look. In v5, surface used elevation.level3 for the container and primary for the icon. The closest v6 roles are surfaceContainerHigh and primary, so the guide can show that instead:

Suggested change

If you omit `variant`, no change is needed. Replace `variant="surface"` with

one of the supported color variants, such as `primaryContainer`.

If you omit `variant`, no change is needed. The `surface` variant was removed. To keep its look, pass the colors directly:

```js

const { colors } = useTheme();

<FAB

icon="plus"

containerColor={colors.surfaceContainerHigh}

contentColor={colors.primary}

/>

```

(via Claude, verify if it makes sense)

satya164 · 2026-10-22T16:57:21Z


+  React.useEffect(() => {
+    if (!visible) {
+      if (Platform.OS === 'web' && typeof document !== 'undefined') {


The typeof document check never fails here. Effects do not run during server rendering, and on web document exists. The extra check makes it look like a case the code has to handle.

Suggested change

if (Platform.OS === 'web' && typeof document !== 'undefined') {

if (Platform.OS === 'web') {

(via Claude, verify if it makes sense)

satya164

Review by Claude

See the inline comments. (via Claude, verify if it makes sense)

satya164 · 2026-10-23T01:26:09Z

@@ -214,7 +228,7 @@ const FABExample = () => {
          alignment={position}
          trigger={{
            icon: 'pencil',


The menu trigger is also an icon-only FAB, but it has no aria-label. With Type set to menu, the trigger shows up in the iOS accessibility tree as a button with no label, and on web its <button> has no accessible name. The icon FAB got aria-label="Compose" in this PR, so the trigger can get one too:

Suggested change

icon: 'pencil',

icon: 'pencil',

'aria-label': 'Compose',

(via Claude, verify if it makes sense)

Add surface and branded variants, apply web hover elevation, and prevent hidden FABs from retaining focus or actions. Keep large icons at 36dp. BREAKING CHANGE: Replace tonalPrimary, tonalSecondary, and tonalTertiary with primaryContainer, secondaryContainer, and tertiaryContainer. The old variant names are removed without aliases.

Remove the surface preset and static elevation override. Apply hover elevation across platforms and restore focus when hiding a focused FAB. Separate hidden and disabled semantics, and rewrite the migration guide around v5 consumer changes.

The branded FAB comes from material-web's md-branded-fab, which is meant for multicolor brand logos and has no icon color token, so it is not one of the MD3 FAB color styles. Removing it also removes the menu-only variant type and the example's special cases for it.

primaryContainer does not match the v5 surface variant, which used a surface container with a primary icon. Point to containerColor and contentColor with the closest v6 roles instead.

Effects do not run during server rendering and document always exists on web, so the check never fails.

The menu trigger is an icon-only FAB, so without a label it is announced as an unnamed button.

Align the variant table and wrap the surface example in a component so it is self-contained and prettier keeps it as written.

Browsers also focus the FAB on a mouse click or tap, so moving focus back to the previous element when it hides could jump into an earlier text field. Check :focus-visible at hide time and blur in the other cases.

userEvent.press is already blocked by pointerEvents none, so the test passed without the guard. A click event still reaches the pressable and fails the test when the guard is removed.

Cover moving focus back after keyboard focus, blurring instead when the previous element is hidden, inert or disconnected or when the FAB was focused by a mouse click, and leaving focus alone when the FAB no longer has it.

Compare the FAB's own style between hover, focus and press states instead of asserting the Surface shadow tokens, and describe the iOS and Android cases by what they check, since React Native 0.85 sends no hover events there by default.

MD3 keeps a focused FAB at level 3. Without this step, folding focus into the hover state would still pass the elevation tests.

The state comparisons only checked that hover changes the style. Android exposes elevation as a number, so assert there that hover raises it and pressing lowers it, and title the web test by what it checks.

The element stub always took focus, so nothing checked the blur after a restore attempt that the browser ignores. Make focus() a no-op on disconnected or unfocusable elements, as browsers do, and cover that case.

Apps using React Navigation also have a useTheme whose colors lack surfaceContainerHigh, so make the source explicit.

likevy added Contributor: Internal v6 labels Sep 8, 2026

likevy requested a review from satya164 September 8, 2026 07:21

satya164 requested changes Sep 10, 2026

View reviewed changes

likevy requested a review from satya164 September 11, 2026 09:25

satya164 requested a balanced review from Copilot September 15, 2026 20:32

Copilot AI reviewed Sep 15, 2026

likevy force-pushed the fix/fab-md3-spec-accuracy branch from ea20e26 to b200183 Compare September 23, 2026 09:29

satya164 reviewed Oct 22, 2026

View reviewed changes

satya164 reviewed Oct 23, 2026

View reviewed changes

Doberjohn added this to the 6.0.0 milestone Oct 30, 2026

likevy added 17 commits October 30, 2026 12:55

fix(fab): address review feedback

517a515

Remove the surface preset and static elevation override. Apply hover elevation across platforms and restore focus when hiding a focused FAB. Separate hidden and disabled semantics, and rewrite the migration guide around v5 consumer changes.

fix(fab): skip hidden focus restoration targets

3dcd14c

docs(fab): show how to keep the surface look after migrating

21783e7

primaryContainer does not match the v5 surface variant, which used a surface container with a primary icon. Point to containerColor and contentColor with the closest v6 roles instead.

refactor(fab): drop the redundant document check

6b2bce8

Effects do not run during server rendering and document always exists on web, so the check never fails.

fix(fab): name the menu trigger in the example

0e1332d

The menu trigger is an icon-only FAB, so without a label it is announced as an unnamed button.

docs(fab): format the migration snippet and table

a1898ae

Align the variant table and wrap the surface example in a component so it is self-contained and prettier keeps it as written.

fix(fab): restore focus only after keyboard focus

651cc08

Browsers also focus the FAB on a mouse click or tap, so moving focus back to the previous element when it hides could jump into an earlier text field. Check :focus-visible at hide time and blur in the other cases.

test(fab): name the disabled FAB test after its behavior

176a274

test(fab): cover the press guard on a hidden FAB

3d9741d

userEvent.press is already blocked by pointerEvents none, so the test passed without the guard. A click event still reaches the pressable and fails the test when the guard is removed.

test(fab): cover focus restoration when a FAB hides on web

512d033

Cover moving focus back after keyboard focus, blurring instead when the previous element is hidden, inert or disconnected or when the FAB was focused by a mouse click, and leaving focus alone when the FAB no longer has it.

test(fab): check that focus alone keeps the resting elevation

3d770f2

MD3 keeps a focused FAB at level 3. Without this step, folding focus into the hover state would still pass the elevation tests.

test(fab): pin the direction of the hover elevation

8022eb7

The state comparisons only checked that hover changes the style. Android exposes elevation as a number, so assert there that hover raises it and pressing lowers it, and title the web test by what it checks.

test(fab): cover the blur fallback when focus can't move back

3c55f90

The element stub always took focus, so nothing checked the blur after a restore attempt that the browser ignores. Make focus() a no-op on disconnected or unfocusable elements, as browsers do, and cover that case.

docs(fab): import useTheme from paper in the surface snippet

55b9ea9

Apps using React Navigation also have a useTheme whose colors lack surfaceContainerHigh, so make the source explicit.

likevy force-pushed the fix/fab-md3-spec-accuracy branch from b200183 to 55b9ea9 Compare October 30, 2026 14:08

Doberjohn mentioned this pull request Oct 30, 2026

Paper 6.0.0: merge order, ground rules and decisions #5150

Open

1 of 47 tasks

Ganeshguru5 mentioned this pull request Nov 1, 2026

fix(fab): expose expanded state on the FAB.Menu trigger #5151

Open

		// Branded artwork has no prescribed icon color; onSurface is a fallback.
		branded: { container: 'surfaceContainerHigh', content: 'onSurface' },

		If you omit `variant`, no change is needed. Replace `variant="surface"` with
		one of the supported color variants, such as `primaryContainer`.

-If you omit `variant`, no change is needed. Replace `variant="surface"` with
-one of the supported color variants, such as `primaryContainer`.
+If you omit `variant`, no change is needed. The `surface` variant was removed. To keep its look, pass the colors directly:
+```js
+const { colors } = useTheme();
+<FAB
+  icon="plus"
+  containerColor={colors.surfaceContainerHigh}
+  contentColor={colors.primary}
+/>
+```

	if (Platform.OS === 'web' && typeof document !== 'undefined') {
	if (Platform.OS === 'web') {

Conversation

likevy commented Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Related issue

Screenshots / Videos

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JKobrynski commented Sep 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

satya164 left a comment • 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!

satya164 Oct 22, 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!

satya164 Oct 22, 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!

satya164 Oct 22, 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!

satya164 left a comment

Choose a reason for hiding this comment

Uh oh!

satya164 Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

likevy commented Sep 8, 2026 •

edited

Loading

satya164 left a comment •

edited

Loading

satya164 Oct 22, 2026 •

edited

Loading

satya164 Oct 22, 2026 •

edited

Loading

satya164 Oct 22, 2026 •

edited

Loading