Paper

Surface component for creating cards, panels, modals, and content containers with visual depth. Supports elevation shadows, automatic background adjustment for nested components, borders, and flexible spacing.

Live Preview

Import

import { Paper } from 'entangle-ui';

Usage

<Paper elevation={1} padding="md">
  <p>Content in a card</p>
</Paper>

Elevation

The elevation prop controls shadow intensity for visual depth.

<Paper elevation={0}>No shadow (flat)</Paper>
<Paper elevation={1}>Small shadow (subtle depth)</Paper>
<Paper elevation={2}>Medium shadow (moderate depth)</Paper>
<Paper elevation={3}>Large shadow (high depth)</Paper>

Elevation	Shadow	Use case
0	None	Flat containers, inline sections
1	Small	Standard cards and panels
2	Medium	Floating panels, dropdown menus
3	Large	Modals, overlays

Nesting

The nestLevel prop adjusts background brightness for visual hierarchy in nested layouts. Higher levels get progressively lighter backgrounds.

<Paper nestLevel={0} padding="xl">
  <h2>Main Container (darkest)</h2>
  <Paper nestLevel={1} padding="lg">
    <h3>Nested Section</h3>
    <Paper nestLevel={2} padding="md">
      <p>Deeply nested content (lightest)</p>
    </Paper>
  </Paper>
</Paper>

Nest Level	Background	Use case
0	Primary (darkest)	Root container
1	Secondary	First-level panels
2	Tertiary	Nested sub-panels
3	Elevated (lightest)	Deeply nested content

Padding

The padding prop uses theme spacing tokens for consistent internal spacing.

<Paper padding="xs">2px padding</Paper>
<Paper padding="sm">4px padding</Paper>
<Paper padding="md">8px padding</Paper>
<Paper padding="lg">12px padding</Paper>
<Paper padding="xl">16px padding</Paper>
<Paper padding="xxl">24px padding</Paper>
<Paper padding="xxxl">32px padding</Paper>

Bordered

The bordered prop adds a subtle border around the paper. Useful for flat containers that need visual separation.

<Paper elevation={0} bordered padding="md">
  Outlined container without shadow
</Paper>

<Paper elevation={1} bordered padding="lg">
  Card with both border and shadow
</Paper>

Expand

The expand prop makes the paper fill the available width and height of its container.

<Paper expand elevation={1} padding="lg">
  <header>Full-size panel</header>
  <main>Fills available space</main>
</Paper>

Custom Radius

Override the default border radius with a custom value.

<Paper customRadius="12px" elevation={2} padding="lg">
  Custom rounded corners
</Paper>

<Paper customRadius={0} elevation={1} padding="md">
  Sharp corners
</Paper>

<Paper customRadius="50%" elevation={2} padding="xl">
  Circular
</Paper>

Combining Props

<Paper elevation={2} nestLevel={1} bordered padding="xl" customRadius="8px">
  <h3>Settings Panel</h3>
  <Paper nestLevel={2} padding="md" bordered>
    <p>Nested settings group</p>
  </Paper>
</Paper>

Props

Prop	Type	Default	Description
children	ReactNode	—	Paper content -- any React elements.
elevation	0 | 1 | 2 | 3	1	Shadow intensity level for visual depth.
bordered	boolean	false	Whether to show a subtle border around the paper.
padding	'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | 'xxxl'	'md'	Internal padding using theme spacing tokens.
nestLevel	0 | 1 | 2 | 3	0	Nesting level for automatic background brightness adjustment.
expand	boolean	false	Whether the paper should fill available width and height.
customRadius	string | number	—	Custom border radius override. Numbers are treated as pixels.
className	string	—	Additional CSS class names.
style	CSSProperties	—	Inline styles.
testId	string	—	Test identifier for automated testing.
ref	Ref<HTMLDivElement>	—	Ref to the underlying div element.

The component also accepts all standard HTML <div> attributes.

Accessibility

• Renders a semantic <div> element
• Use appropriate headings and landmarks within Paper content for screen reader navigation
• Elevation is purely visual and does not affect the accessibility tree
• Ensure sufficient color contrast between nested Paper levels and their text content