Mask is used to display content in a specific shape.

Figma:

Responsive:

Adaptive:

Props

Component props
Name
Type
Default
children
React.Node
-

The content to be masked.

height
number | string
-

Use numbers for pixels (height={100}) and strings for percentages (height="100%").

rounding
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | "circle"
0

Specifies the corner radius to apply. See the Rounding example for more details.

wash
boolean
false

Applies a wash to provide contrast when the masked content is nearly white. See the Wash example for more details.

width
number | string
-

Use numbers for pixels (width={100}) and strings for percentages (width="100%").

willChangeTransform
boolean
true

Mask applies the style will-change: transform by default as a performance optimization. In certain specific scenarios, this can be problematic. This prop can be used to turn off that optimization. See the willChangeTransform example for more details.

Accessibility

Variants

Masking a color

import { Box, Flex, Mask } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Mask height={70} rounding="circle" width={70}>
        <Box color="successBase" height={70} width={70} />
      </Mask>
    </Flex>
  );
}

Masking other content

You can compose images with other content (like images or videos) to produce different shapes like rounded rectangles or circles.

import { Box, Flex, Mask } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Box maxWidth={300}>
        <Mask rounding="circle">
          <img
            alt="weakendclub.com"
            src="https://i.ibb.co/121JJzC/stock7.jpg"
            style={{ maxWidth: '100%', display: 'block' }}
          />
        </Mask>
      </Box>
    </Flex>
  );
}

Adding a wash

If you expect the masked content to be nearly white, you can apply a wash to emphasize the edge of the mask.

import { Box, Flex, Mask } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Box maxWidth={300}>
        <Mask rounding={2} wash>
          <img
            alt="subliming.tumblr.com"
            src="https://i.ibb.co/8BSrgzX/stock8.jpg"
            style={{ maxWidth: '100%', display: 'block' }}
          />
        </Mask>
      </Box>
    </Flex>
  );
}

Rounding

rounding="circle"
rounding={0}
rounding={1}
rounding={2}
rounding={3}
rounding={4}
rounding={5}
rounding={6}
rounding={7}
rounding={8}

willChangeTransform

If you want to turn off the willChange:transform property for rendering reasons, you can set this to false. See MDN for more details.

import { Box, Flex, Mask } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Box maxWidth={300}>
        <Mask rounding={2} willChangeTransform={false}>
          <img
            alt="subliming.tumblr.com"
            src="https://i.ibb.co/8BSrgzX/stock8.jpg"
            style={{ maxWidth: '100%', display: 'block' }}
          />
        </Mask>
      </Box>
    </Flex>
  );
}

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Component is not currently available in Figma.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.

Letterbox
Letterbox is useful if you have some source media which is larger than the area you want to display it in. For instance, you might have a really tall image and want it to be displayed in a neatly cropped square.