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

N/A

Responsive:

Ready

Adaptive:

N/A

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.

Edit page on GitHub