# Surface
Package: @mantine/core
Import: import { Surface } from '@mantine/core';
Description: Depth-aware background primitive with elevation levels for dark color scheme

## 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](https://alpha.mantine.dev/llms/core-paper.md) component and supports the same props:

```tsx
import { Surface, Text } from '@mantine/core';

function Demo() {
  return (
    <Surface shadow="xs" radius="md" withBorder={false} p="xl">
      <Text>Surface is the depth-aware background primitive</Text>
      <Text>
        Use it to create cards, panels and other containers that require background with optional
        shadow and border
      </Text>
    </Surface>
  );
}
```


## Surface levels

`Surface` has three depth levels, each level uses a surface color token of the [colors system](https://alpha.mantine.dev/llms/theming-colors.md):

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:

```tsx
import { Surface, Text } from '@mantine/core';

function Demo() {
  return (
    <Surface p="md" radius="md" withBorder>
      <Text size="sm">Level 0 – surface-page</Text>
      <Surface p="md" radius="md" mt="md" withBorder>
        <Text size="sm">Level 1 – surface-panel</Text>
        <Surface p="md" radius="md" mt="md" withBorder>
          <Text size="sm">Level 2 – surface-panel-2</Text>
        </Surface>
      </Surface>
    </Surface>
  );
}
```


Set `autoDepth={false}` to render the surface at the same level as its parent:

```tsx
import { Surface } from '@mantine/core';

function Demo() {
  return (
    <Surface p="md">
      Level 0
      <Surface p="md" autoDepth={false}>
        Also level 0 – same background as the parent
      </Surface>
    </Surface>
  );
}
```

## 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"`):

```tsx
import { Surface, Text } from '@mantine/core';

function Demo() {
  return (
    <Surface level={2} p="md" radius="md" withBorder>
      <Text size="sm">Explicit level 2</Text>
      <Surface level="-1" p="md" radius="md" mt="md" withBorder>
        <Text size="sm">Relative level "-1" – one level below the parent, resolves to 1</Text>
      </Surface>
      <Surface level={0} p="md" radius="md" mt="md" withBorder>
        <Text size="sm">Explicit level 0 – page background</Text>
      </Surface>
    </Surface>
  );
}
```


## 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:

```css
.surface {
  &[data-mantine-surface-level='2'] {
    border: 1px solid var(--mantine-color-border-subtle);
  }
}
```

## 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:

```tsx
import { Surface, Text, useSurfaceDepth } from '@mantine/core';

function LevelLabel() {
  const level = useSurfaceDepth();
  return <Text>Surface level: {level}</Text>;
}

function Demo() {
  return (
    <Surface p="md">
      <LevelLabel />
      <Surface p="md">
        <LevelLabel />
      </Surface>
    </Surface>
  );
}
```

## 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](https://alpha.mantine.dev/llms/theming-colors.md) for all keys:

```tsx
import { createTheme, MantineProvider } from '@mantine/core';

const theme = createTheme({
  surfaces: {
    dark: {
      panel: '#101113',
      panel2: '#17181c',
    },
  },
});

function Demo() {
  return <MantineProvider theme={theme}>{/* Your app */}</MantineProvider>;
}
```

## Migrating from Paper

[Paper](https://alpha.mantine.dev/llms/core-paper.md) 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:

```tsx
import { Paper, Surface } from '@mantine/core';

// ❌ Deprecated
function Demo() {
  return <Paper shadow="sm" p="md">Content</Paper>;
}

// ✅ Use Surface instead
function Demo() {
  return <Surface shadow="sm" p="md">Content</Surface>;
}
```

A standalone `Surface` has the same background as `Paper`. Unlike `Paper`, nested surfaces
step up one level in dark color scheme.


#### Props

**Surface props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| autoDepth | boolean | - | Determines whether the surface level is automatically incremented by 1 relative to the parent surface, `true` by default |
| level | string \| number | - | Explicit surface depth level. Accepts an absolute number/string (`0`–`2`) or a relative value (`'+1'`, `'-1'`) applied against the parent surface level. When set, overrides `autoDepth`. |
| radius | MantineRadius \| number | theme.defaultRadius | Key of `theme.radius` or any valid CSS value to set border-radius, numbers are converted to rem |
| shadow | MantineShadow | - | Key of `theme.shadows` or any valid CSS value to set `box-shadow` |
| withBorder | boolean | - | Adds border to the root element |


#### Styles API

Surface component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**Surface selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-Surface-root | Root element |

**Surface CSS variables**

| Selector | Variable | Description |
|----------|----------|-------------|
| root | --surface-radius | Controls `border-radius` |
| root | --surface-shadow | Controls `box-shadow` |

**Surface data attributes**

| Selector | Attribute | Condition | Value |
|----------|-----------|-----------|-------|
| root | data-with-border | `withBorder` prop is set | - |
| root | data-mantine-surface-level | - | resolved surface level, `0`–`2` |
