feat(theme): add semantic container color prop to Surface by hristototov · Pull Request #5121 · callstack/react-native-paper

hristototov · 2026-09-14T12:22:29Z

Motivation

Surface takes its background from elevation, so a component can't use an MD3 surface role without passing a raw color. The new container prop takes a surface role and resolves it from the theme. elevation then only sets the shadow.

Menu, Banner and Searchbar now use it. With LightTheme and DarkTheme they look the same. With the dynamic themes on Android 12+, Menu and Banner use the system surface colors.

Related issue

Fixes #5119

Screenshots / Videos

light-mode.mov

dark-mode.mov

Test plan

Surface example, light and dark: every "Semantic container colors" tile is visible.
Banner example: "Set custom theme" shows light text on a dark background.

JKobrynski

LGTM, @satya164

Copilot

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

…into hristototov/surface-semantic-container-color

satya164 · 2026-10-22T16:26:35Z

Review by Claude

iOS

Banner text is unreadable with the custom theme in the Banner example. (via Claude, verify if it makes sense)

Open the Banner example.
Press "Set custom theme".

What happens: the text turns near white (onSurface: Palette.tertiary100) but the background stays the light surfaceContainerLow. The example overrides colors.elevation.level1 for the background, and Banner no longer reads it.

What should happen: the banner shows the dark tertiary background with light text, like on main. Change the example to override surfaceContainerLow instead of elevation.level1.

Surface example: role labels break mid-word and two tiles are invisible. (via Claude, verify if it makes sense)

Open the Surface example.
Scroll the "Semantic container colors" row.

What happens: surfaceContainerLowest and surfaceContainerLow wrap as "surfaceContainerLo / west" and "surfaceContainerLo / w" in the 120 pt tiles. The surface and surfaceBright tiles have the same color as the screen background, so they look like plain text with no tile.

What should happen: each label fits on its own line and each tile is visible against the screen background, for example with a border or mode="elevated".

Android

Banner text is unreadable with the custom theme in the Banner example. (via Claude, verify if it makes sense)

Same steps and cause as on iOS.

With the dynamic theme, Banner and Menu change color compared to main. (via Claude, verify if it makes sense)

Use the example app on Android 12 or newer, where it uses DynamicLightTheme by default.
Open the Banner example.

What happens: the background now uses the wallpaper based system_surface_container_* colors. On main it used colors.elevation.level1 and level2, which DynamicLightTheme and DynamicDarkTheme keep from the static theme. The color change itself is fine, but the migration guide says "the rendered color is unchanged", which is not true for the dynamic themes.

What should happen: the migration guide says that the color changes when you use the dynamic themes on Android.

Web

Banner text is unreadable with the custom theme in the Banner example. (via Claude, verify if it makes sense)

Same steps and cause as on iOS.

(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-22T16:27:51Z

      {...rest}
      style={[surfaceStyle, style]}
      theme={theme}
+      container="surfaceContainerLow"


This breaks the "Set custom theme" action in the Banner example on iOS, Android and web. example/src/Examples/BannerExample.tsx sets the custom background through colors.elevation.level1 and the text through onSurface: Palette.tertiary100. Banner no longer reads elevation.level1, so the near white text now sits on the light surfaceContainerLow background.

Update the example to override the role Banner now reads:

const customTheme = { ...defaultTheme, colors: { ...defaultTheme.colors, onSurface: Palette.tertiary100, surfaceContainerLow: Palette.tertiary50, primary: Palette.tertiary10, }, };

Any app that customized elevation.level1 to style Banner (or elevation.level2 for Menu) hits the same problem, so the migration guide should also say which role to override. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T16:27:51Z

+     * variant-driven fills outside the surface family should keep resolving
+     * their own tokens and pass the result via `backgroundColor`.
+     */
+    container?: SurfaceRole;


The existing backgroundColor prop already does this. backgroundColor={theme.colors.surfaceContainer} resolves from the theme, follows theme changes, and makes elevation control only the shadow, because it also wins over the elevation color. Searchbar (backgroundColor={theme.colors.surfaceContainerHigh}) and Dialog (surfaceContainerHigh) already use that pattern. With this PR, the library has two ways to set a surface role, and the new JSDoc tells contributors to prefer container, which those two components do not follow.

The name is also unclear. container="surface" or container="inverseSurface" does not name a container, and "container" in this library usually means a wrapper element (contentContainerStyle, styles.container).

Suggested fix: drop container and SurfaceRole, and pass backgroundColor={theme.colors.surfaceContainer} in Menu and backgroundColor={theme.colors.surfaceContainerLow} in Banner. The behavior stays the same and the public API does not grow. If you keep the prop, migrate Searchbar and Dialog to it so there is one pattern. (via Claude, verify if it makes sense)

Kept container so components can name an MD3 role instead of resolving a raw color, and moved Searchbar to it. I left Dialog as is, because it sets its color through Modal's public contentBackgroundColor and moving it would mean adding a new Modal prop.

satya164 · 2026-10-22T16:27:51Z

+     *
+     * Prefer `container` when the fill is an MD3 surface-family role (as
+     * component specs define it, e.g. menus use `surfaceContainer`). Use
+     * `backgroundColor` only for raw, non-semantic colors. Components with
+     * variant-driven fills outside the surface family should keep resolving
+     * their own tokens and pass the result via `backgroundColor`.


If the prop stays, this paragraph is guidance for library contributors, not for users of Surface. It shows up in the public API docs. Consider removing it.

Suggested change

*

* Prefer `container` when the fill is an MD3 surface-family role (as

* component specs define it, e.g. menus use `surfaceContainer`). Use

* `backgroundColor` only for raw, non-semantic colors. Components with

* variant-driven fills outside the surface family should keep resolving

* their own tokens and pass the result via `backgroundColor`.

(via Claude, verify if it makes sense)

satya164 · 2026-10-22T16:27:51Z

  const backgroundColor =
-    customBackgroundColor ?? colors.elevation?.[`level${elevation}`];
+    customBackgroundColor ??
+    (container != null ? colors[container] : undefined) ??
+    colors.elevation?.[`level${elevation}`];


container is either a role or undefined, and colors[container] is always a color, so the : undefined) ?? step is not needed. A plain ternary reads easier:

Suggested change

const backgroundColor =

customBackgroundColor ?? colors.elevation?.[`level${elevation}`];

customBackgroundColor ??

(container != null ? colors[container] : undefined) ??

colors.elevation?.[`level${elevation}`];

const backgroundColor =

customBackgroundColor ??

(container ? colors[container] : colors.elevation?.[`level${elevation}`]);

(via Claude, verify if it makes sense)

satya164 · 2026-10-22T16:27:52Z


+### Banner
+
+The banner background is now always `theme.colors.surfaceContainerLow` and no longer depends on the `elevation` prop, which only controls the shadow. At the default `elevation` of `1` the rendered color is unchanged.


"The rendered color is unchanged" is true for LightTheme and DarkTheme only. DynamicLightTheme and DynamicDarkTheme on Android 12 and newer replace surfaceContainer* with PlatformColor values but keep the static elevation colors. So Banner and Menu change from the static tint to the wallpaper based color there. The example app uses the dynamic theme by default on Android:

main this PR

The guide should also tell users which role to override now, since a custom elevation.level1 no longer applies:

Suggested change

The banner background is now always `theme.colors.surfaceContainerLow` and no longer depends on the `elevation` prop, which only controls the shadow. At the default `elevation` of `1` the rendered color is unchanged.

The banner background is now always `theme.colors.surfaceContainerLow` and no longer depends on the `elevation` prop, which only controls the shadow. If you customized `theme.colors.elevation.level1` to change the banner background, customize `theme.colors.surfaceContainerLow` instead. With `LightTheme` and `DarkTheme`, the rendered color at the default `elevation` of `1` is unchanged. With `DynamicLightTheme` and `DynamicDarkTheme` on Android 12 and newer, the banner now uses the system surface color.

(via Claude, verify if it makes sense)

satya164 · 2026-10-22T16:27:52Z

+
+### Menu
+
+The menu background is now always `theme.colors.surfaceContainer`, following the Material Design 3 spec, and no longer depends on the `elevation` prop, which only controls the shadow. At the default `elevation` of `2` the rendered color is unchanged.


Same as for Banner above:

Suggested change

The menu background is now always `theme.colors.surfaceContainer`, following the Material Design 3 spec, and no longer depends on the `elevation` prop, which only controls the shadow. At the default `elevation` of `2` the rendered color is unchanged.

The menu background is now always `theme.colors.surfaceContainer`, following the Material Design 3 spec, and no longer depends on the `elevation` prop, which only controls the shadow. If you customized `theme.colors.elevation.level2` to change the menu background, customize `theme.colors.surfaceContainer` instead. With `LightTheme` and `DarkTheme`, the rendered color at the default `elevation` of `2` is unchanged. With `DynamicLightTheme` and `DynamicDarkTheme` on Android 12 and newer, the menu now uses the system surface color.

(via Claude, verify if it makes sense)

satya164 · 2026-10-22T16:27:52Z

 - The `pointerEvents` prop is no longer supported as it's deprecated in React Native Web. You can specify `pointerEvents` in the `style` prop instead.
 - The `overflow: 'hidden'` style is no longer supported in `style` as it can clip shadows. You can nest a `View` inside the `Surface` and apply `overflow: 'hidden'` to that instead.
 - The default `testID` for `Surface` was removed. You can specify a `testID` explicitly if you need it.
+- A new `container` prop sets the background to a semantic surface-family color role from the theme (e.g. `container="surfaceContainerLow"`). When `container` is set, `elevation` only controls the shadow. Precedence: `backgroundColor` > `container` > the color derived from `elevation`.


This bullet sits between the style bullet and the "e.g.:" diff that shows how to migrate style, so the example now reads as if it belongs to container. It also describes a new feature, not a step users need to take. The Surface API docs already cover it, so I would remove the bullet:

Suggested change

- A new `container` prop sets the background to a semantic surface-family color role from the theme (e.g. `container="surfaceContainerLow"`). When `container` is set, `elevation` only controls the shadow. Precedence: `backgroundColor` > `container` > the color derived from `elevation`.

(via Claude, verify if it makes sense)

satya164 · 2026-10-22T16:27:52Z

+            <Surface
+              key={role}
+              style={styles.surface}
+              borderRadius={8}
+              mode="flat"
+              container={role}
+            >


Two problems with this row on iOS and Android:

The surface and surfaceBright tiles have the same color as the screen, so they look like plain text with no tile.

In the 120 pt tiles, surfaceContainerLowest and surfaceContainerLow wrap mid-word ("surfaceContainerLo / west").

An elevated tile makes every role visible, and it also shows that elevation only sets the shadow here. For the wrapping, use wider tiles for this row or a smaller text variant.

Suggested change

<Surface

key={role}

style={styles.surface}

borderRadius={8}

mode="flat"

container={role}

>

<Surface

key={role}

style={styles.surface}

borderRadius={8}

elevation={1}

container={role}

>

(via Claude, verify if it makes sense)

The elevated tile does not fix this in dark theme, because surface and surfaceDim are both neutral6 there and the shadow does not show on the dark screen (screenshots). A hairline outlineVariant border shows every tile in light and dark theme:

Suggested change

<Surface

key={role}

style={styles.surface}

borderRadius={8}

mode="flat"

container={role}

>

<Surface

key={role}

style={[

styles.surface,

{

borderWidth: StyleSheet.hairlineWidth,

borderColor: theme.colors.outlineVariant,

},

]}

borderRadius={8}

mode="flat"

container={role}

>

(via Claude, verify if it makes sense)

satya164 · 2026-10-22T23:51:27Z

Review by Claude

iOS

Surface example, dark theme: the surface and surfaceDim tiles are invisible, also with the elevated tile suggested earlier. (via Claude, verify if it makes sense)

Turn on "Dark Theme" in the drawer.
Open the Surface example and look at the "Semantic container colors" row.

What happens: in DarkTheme, surface and surfaceDim both use neutral6, the same color as the screen. With elevation={1} and mode="elevated" (the earlier suggestion), the shadow does not show on the dark screen, so both tiles still look like plain text.

What should happen: every tile is visible in light and dark theme. A hairline outlineVariant border does this (see the web screenshot below).

Android

Surface example, dark theme: the surface and surfaceDim tiles are invisible. (via Claude, verify if it makes sense)

Same steps and cause as on iOS.

Web

Surface example, dark theme: the surface and surfaceDim tiles are invisible. (via Claude, verify if it makes sense)

Same steps and cause as on iOS.

(via Claude, verify if it makes sense)

satya164

Review by Claude

docs/6.x/docs/guides/theming.mdx (line 109) still names menus as an example of surfaces tinted by theme.colors.elevation. With this PR, Menu and Banner take their background from surfaceContainer and surfaceContainerLow, so a reader who changes elevation.level2 to restyle menus sees no effect. Drop "or menus" there, or add that Menu and Banner use the surfaceContainer* roles. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T23:56:16Z

+     * Semantic color role of the Surface background, resolved from the
+     * theme, e.g. `container="surfaceContainerLow"` renders with
+     * `theme.colors.surfaceContainerLow`.


The generated docs page shows the type of this prop as SurfaceRole only, so readers cannot see which values it accepts. The values are only listed in src/theme/types/color.ts, which the docs do not show. List them here:

Suggested change

* Semantic color role of the Surface background, resolved from the

* theme, e.g. `container="surfaceContainerLow"` renders with

* `theme.colors.surfaceContainerLow`.

* Semantic color role of the Surface background, resolved from the

* theme, e.g. `container="surfaceContainerLow"` renders with

* `theme.colors.surfaceContainerLow`. Accepted roles: `surface`,

* `surfaceDim`, `surfaceBright`, `surfaceVariant`,

* `surfaceContainerLowest`, `surfaceContainerLow`, `surfaceContainer`,

* `surfaceContainerHigh`, `surfaceContainerHighest` and `inverseSurface`.

(via Claude, verify if it makes sense)

…into hristototov/surface-semantic-container-color

hristototov · 2026-10-24T08:53:44Z

Review by Claude

docs/6.x/docs/guides/theming.mdx (line 109) still names menus as an example of surfaces tinted by theme.colors.elevation. With this PR, Menu and Banner take their background from surfaceContainer and surfaceContainerLow, so a reader who changes elevation.level2 to restyle menus sees no effect. Drop "or menus" there, or add that Menu and Banner use the surfaceContainer* roles. (via Claude, verify if it makes sense)

Updated theming.mdx: the elevation note now names only app bars, and says that menus and banners use the surfaceContainer and surfaceContainerLow roles instead.

feat: add semantic container color prop to Surface

b630681

hristototov requested review from JKobrynski, adrcotfas and satya164 and removed request for JKobrynski and satya164 September 14, 2026 12:29

JKobrynski approved these changes Sep 15, 2026

View reviewed changes

satya164 added the Contributor: Internal label Sep 15, 2026

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

Copilot AI reviewed Sep 15, 2026

Merge branch 'main' of https://github.com/callstack/react-native-paper …

a58698d

…into hristototov/surface-semantic-container-color

satya164 reviewed Oct 22, 2026

View reviewed changes

Hristo Totov added 2 commits October 24, 2026 11:43

Merge branch 'main' of https://github.com/callstack/react-native-paper …

9607a6a

…into hristototov/surface-semantic-container-color

fix: cr comments

a61aeb7

hristototov requested a review from satya164 October 24, 2026 08:54


		### Banner

		The banner background is now always `theme.colors.surfaceContainerLow` and no longer depends on the `elevation` prop, which only controls the shadow. At the default `elevation` of `1` the rendered color is unchanged.


		### Menu

		The menu background is now always `theme.colors.surfaceContainer`, following the Material Design 3 spec, and no longer depends on the `elevation` prop, which only controls the shadow. At the default `elevation` of `2` the rendered color is unchanged.

Conversation

hristototov commented Sep 14, 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!

JKobrynski left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

satya164 commented Oct 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

iOS

Android

Web

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!

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!

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!

satya164 commented Oct 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

iOS

Android

Web

Uh oh!

satya164 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hristototov commented Oct 24, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hristototov commented Sep 14, 2026 •

edited

Loading

satya164 commented Oct 22, 2026 •

edited

Loading

satya164 left a comment •

edited

Loading

satya164 commented Oct 22, 2026 •

edited

Loading