Surface | iTwinUI

The Surface container allows content to appear elevated through the use of a drop shadow.

import * as React from 'react';
import { Surface } from '@itwin/itwinui-react';

export default () => {
  return (
    <Surface elevation={4} className='demo-surface'>
      <p>This is a surface</p>
    </Surface>
  );
};

Variants

Elevation

Elevation is measured as the distance between surfaces.

import * as React from 'react';
import { Surface } from '@itwin/itwinui-react';

export default () => {
  return (
    <>
      <div className='demo-container'>
        <Surface elevation={0} className='demo-card'>
          <p>Elevation 0 (0dp)</p>
        </Surface>
        <Surface elevation={1} className='demo-card'>
          <p>Elevation 1 (2dp)</p>
        </Surface>
        <Surface elevation={2} className='demo-card'>
          <p>Elevation 2 (4dp)</p>
        </Surface>
      </div>
      <div className='demo-container'>
        <Surface elevation={3} className='demo-card'>
          <p>Elevation 3 (8dp)</p>
        </Surface>
        <Surface elevation={4} className='demo-card'>
          <p>Elevation 4 (16dp)</p>
        </Surface>
        <Surface elevation={5} className='demo-card'>
          <p>Elevation 5 (24dp)</p>
        </Surface>
      </div>
    </>
  );
};

The distance from the front of one surface to the front of another is measured along the z-axis in density-independent pixels (dp) and depicted using drop shadows.

We support from 0dp up to 24dp in elevation with the shadows copying real life, getting larger and more blurred the further they go away from the surface. 0dp represents the absence of drop shadow. Next are 2dp and 4dp, then scaling directly up to 8dp, 16dp, to finally reach the maximal elevation of 24dp.

Header & Body

The surface component also has customizable subcomponents for header and body

import * as React from 'react';
import { Surface, Text, IconButton, Flex } from '@itwin/itwinui-react';
import { SvgSettings } from '@itwin/itwinui-icons-react';

export default () => {
  return (
    <Surface elevation={4}>
      <Surface.Header as={Flex} justifyContent='space-between'>
        <Text variant='subheading' as='h2'>
          Custom surface
        </Text>
        <IconButton label='Settings' styleType='borderless'>
          <SvgSettings />
        </IconButton>
      </Surface.Header>
      <Surface.Body isPadded={true}>
        <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
          eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
          minim veniam, quis nostrud exercitation ullamco laboris nisi ut
          aliquip ex ea commodo consequat. Duis aute irure dolor in
          reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
          pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
          culpa qui officia deserunt mollit anim id est laborum.
        </p>
      </Surface.Body>
    </Surface>
  );
};

By default, the surface’s body component includes padding. This can be disabled using the isPadded prop

import * as React from 'react';
import { Surface, Text, Anchor, Divider } from '@itwin/itwinui-react';

export default () => {
  return (
    <Surface elevation={3} className='demo-card'>
      <Surface.Header>
        <Text id='surface-header' variant='subheading' as='h2'>
          Surface with overflow & no body padding
        </Text>
      </Surface.Header>
      <Surface.Body
        tabIndex={0}
        role='group'
        aria-labelledby='surface-header'
        isPadded={false}
      >
        <div className='demo-container'>
          <div className='demo-list'>
            <div className='demo-list-item'>
              <Anchor>Daily log</Anchor>
            </div>
            <Divider />
            <div className='demo-list-item'>
              <Anchor>Inspections</Anchor>
            </div>
            <Divider />
            <div className='demo-list-item'>
              <Anchor>Issues</Anchor>
            </div>
            <Divider />
            <div className='demo-list-item'>
              <Anchor>Observations</Anchor>
            </div>
            <Divider />
            <div className='demo-list-item'>
              <Anchor>RFIs</Anchor>
            </div>
            <Divider />
            <div className='demo-list-item'>
              <Anchor>Weather delay notices</Anchor>
            </div>
          </div>
        </div>
      </Surface.Body>
    </Surface>
  );
};

Props

Prop	Description	Default
elevation	Sets the elevation of the surface 0 \| 1 \| 2 \| 3 \| 4 \| 5
border	Sets the border of the surface. Can be a boolean to toggle the default border, or a string value to specify a custom border. string \| boolean	true
children	Content in the surface. ReactNode
as	"symbol" \| "object" \| "div" \| "a" \| "abbr" \| "address" \| "area" \| "article" \| "aside" \| "audio" \| "b" \| "base" \| "bdi" \| "bdo" \| "big" \| "blockquote" \| "body" \| "br" \| "button" \| "canvas" \| ... 158 more ... \| FunctionComponent<...>