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. While the ideal solution to this problem is to update the source image, this might not always be possible for either cost or performance reasons.

Letterbox should be used in situations where you would otherwise use the CSS property background-size: cover.

Figma:

Responsive:

Adaptive:

A11y:

Props

Component props
Name
Type
Default
contentAspectRatio
Required
number
-

Proportional relationship between width and height of element.

height
Required
number
-

Desired final height of element in pixels.

width
Required
number
-

Desired final width of element in pixels.

children
React.Node
-

The media to be displayed.

Accessibility

Variants

Much of the math and understanding about Letterbox comes from Vjeaux's excellent blog post on image resizing.

Tall content (564:806)

import { Flex, Image, Letterbox } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Letterbox contentAspectRatio={564 / 806} height={200} width={200}>
        <Image
          alt="Example image"
          naturalHeight={806}
          naturalWidth={564}
          src="https://i.ibb.co/jVR29XV/stock5.jpg"
        />
      </Letterbox>
    </Flex>
  );
}

Wide content (564:517)

import { Flex, Image, Letterbox } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Letterbox contentAspectRatio={564 / 517} height={200} width={200}>
        <Image
          alt="Example image"
          naturalHeight={517}
          naturalWidth={564}
          src="https://i.ibb.co/SB0pXgS/stock4.jpg"
        />
      </Letterbox>
    </Flex>
  );
}

Square content (1:1)

import { Flex, Image, Letterbox } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Letterbox contentAspectRatio={1} height={200} width={200}>
        <Image
          alt="Example image"
          naturalHeight={1}
          naturalWidth={1}
          src="https://i.ibb.co/FY2MKr5/stock6.jpg"
        />
      </Letterbox>
    </Flex>
  );
}

Square content (1:1) in a vertical frame

import { Flex, Image, Letterbox } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Letterbox contentAspectRatio={1} height={300} width={200}>
        <Image
          alt="Example image"
          naturalHeight={1}
          naturalWidth={1}
          src="https://i.ibb.co/d0pQsJz/stock3.jpg"
        />
      </Letterbox>
    </Flex>
  );
}

Square content (1:1) in a horizontal frame

import { Flex, Image, Letterbox } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Letterbox contentAspectRatio={1} height={200} width={300}>
        <Image
          alt="Example image"
          naturalHeight={1}
          naturalWidth={1}
          src="https://i.ibb.co/d0pQsJz/stock3.jpg"
        />
      </Letterbox>
    </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.

Mask
Mask is used to display content in a specific shape.