Surface
Depth-aware background primitive with elevation levels for dark color scheme
Polymorphic
Source
Package
Usage
Surface is a container with background, optional shadow, border and border-radius.
Its background color depends on the depth level. Surface replaces the deprecated
Paper component and supports the same props:
Surface is the depth-aware background primitive
Use it to create cards, panels and other containers that require background with optional shadow and border
Surface levels
Surface has three depth levels, each level uses a surface color token of the colors system:
In dark color scheme each level is one shade lighter than the previous one. In light color scheme all levels are white by default, switch to dark color scheme to see the demos on this page.
Automatic depth
By default, a Surface without a parent Surface has level 0 and matches the page background.
Each nested Surface renders one level above its parent, deeper nesting stays at level 2:
Level 0 – surface-page
Level 1 – surface-panel
Level 2 – surface-panel-2
Set autoDepth={false} to render the surface at the same level as its parent:
level prop
Set level prop to set the depth explicitly. It accepts an absolute value (0–2)
or a value relative to the parent surface level ("+1", "-1"):
Explicit level 2
Relative level "-1" – one level below the parent, resolves to 1
Explicit level 0 – page background
Styling surfaces by level
The root element has data-mantine-surface-level attribute with the resolved level.
Use it to style surfaces depending on the depth, for example, to add a border only to the deepest surfaces:
useSurfaceDepth
useSurfaceDepth hook returns the level of the closest parent Surface, 0 when there is none.
Use it in custom components that need to know the level of the surface they are rendered in:
Customize surface colors
Use the surfaces key of the theme to change surface colors for each color scheme.
The change applies to all components that use these colors, not only to Surface.
Note that page is also the background of the page, modals and dropdowns, see the
colors guide for all keys:
Migrating from Paper
Paper is deprecated in 10.0 and will be removed in 11.0. Surface supports
all Paper props, in most cases it is enough to replace the component name:
A standalone Surface has the same background as Paper. Unlike Paper, nested surfaces
step up one level in dark color scheme.
Polymorphic component
Surface is a polymorphic component – its default root element is div, but it can be changed to any other element or component with the component prop:
You can also use components in the component prop, for example, Next.js Link:
Polymorphic components with TypeScript
Note that polymorphic component prop types are different from regular components – they do not extend HTML element props of the default element. For example,
SurfacePropsdoes not extendReact.ComponentProps'<'div'>'althoughdivis the default element.If you want to create a wrapper for a polymorphic component that is not polymorphic (does not support the
componentprop), then your component props interface should extend HTML element props, for example:If you want your component to remain polymorphic after wrapping, use the
polymorphicfunction described in this guide.