XDSAspectRatio@xds/core · AspectRatio
Preview coming soon

Usage

Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.

Best practices

GuidancePractices
DoExpress the ratio as a fraction like `16/9` or `4/3` for readability.
DoUse for media that needs consistent proportions across screen sizes.
Don'tUse for general layout containers — use standard layout components instead.
Don'tNest AspectRatio containers — one level is sufficient.

Import

ts
import {XDSAspectRatio} from '@xds/core/AspectRatio'

Props

PropTypeDescription
ratiorequired
numberAspect ratio as width/height (e.g. 16/9, 1).
childrenrequired
ReactNodeContent positioned absolutely to fill the container.
xstyle
StyleXStylesStyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Examples

Common configurations, variations, and states.
AspectRatio — 16:9 Widescreen Image16:9 widescreen aspect ratio wrapping an image.
tsx
'use client';
​
import {XDSAspectRatio} from '@xds/core/AspectRatio';
import {XDSCenter} from '@xds/core/Center';
​
export default function AspectRatioWidescreen() {
  return (
    <XDSCenter width={600}>
      <XDSAspectRatio ratio={16 / 9}>
        <img
          src="https://lookaside.facebook.com/assets/xds_oss/light-scene-horizontal-1.png"
          alt="16:9 widescreen"
          style={{
            width: '100%',
            height: '100%',
            objectFit: 'cover',
          }}
        />
      </XDSAspectRatio>
    </XDSCenter>
  );
}
AspectRatio — Image GalleryGrid of images with consistent 4:3 aspect ratios.
tsx
'use client';
​
import {XDSAspectRatio} from '@xds/core/AspectRatio';
import {XDSGrid} from '@xds/core/Grid';
​
const images = [
  {id: 1, alt: 'Mountain landscape'},
  {id: 2, alt: 'Ocean sunset'},
  {id: 3, alt: 'Forest trail'},
  {id: 4, alt: 'City skyline'},
  {id: 5, alt: 'Desert dunes'},
  {id: 6, alt: 'Snowy peaks'},
];
​
export default function AspectRatioImageGallery() {
  return (
    <XDSGrid columns={3} gap={4} width="100%">
      {images.map(({id, alt}) => (
        <XDSAspectRatio key={id} ratio={4 / 3}>
          <img
            src="https://lookaside.facebook.com/assets/xds_oss/illustrative-horizontal-1.jpg"
            alt={alt}
            style={{
              width: '100%',
              height: '100%',
              objectFit: 'cover',
              borderRadius: 8,
            }}
          />
        </XDSAspectRatio>
      ))}
    </XDSGrid>
  );
}
AspectRatio — Loading SkeletonAspect ratio container with a skeleton loading placeholder.
tsx
'use client';
​
import {XDSAspectRatio} from '@xds/core/AspectRatio';
import {XDSSkeleton} from '@xds/core/Skeleton';
import {XDSCenter} from '@xds/core/Center';
​
export default function AspectRatioWithSkeleton() {
  return (
    <XDSCenter width={600}>
      <XDSAspectRatio ratio={16 / 9}>
        <XDSSkeleton width="100%" height="100%" />
      </XDSAspectRatio>
    </XDSCenter>
  );
}
AspectRatio — Square Image1:1 square aspect ratio, ideal for avatars and Instagram-style images.
tsx
'use client';
​
import {XDSAspectRatio} from '@xds/core/AspectRatio';
import {XDSCenter} from '@xds/core/Center';
​
export default function AspectRatioSquareImage() {
  return (
    <XDSCenter width={300}>
      <XDSAspectRatio ratio={1}>
        <img
          src="https://lookaside.facebook.com/assets/xds_oss/light-home-square-1.png"
          alt="1:1 square"
          style={{
            width: '100%',
            height: '100%',
            objectFit: 'cover',
          }}
        />
      </XDSAspectRatio>
    </XDSCenter>
  );
}

Showcase source

tsx
'use client';
​
import * as stylex from '@stylexjs/stylex';
import {XDSAspectRatio} from '@xds/core/AspectRatio';
import {XDSCenter} from '@xds/core/Center';
import {XDSHStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
import {colorVars, radiusVars} from '@xds/core/theme/tokens.stylex';
​
const s = stylex.create({
  square: {width: 120},
  fourThree: {width: 160},
  widescreen: {width: 200},
  box: {
    backgroundColor: colorVars['--color-background-muted'],
    border: `1px solid ${colorVars['--color-border']}`,
    borderRadius: radiusVars['--radius-container'],
  },
});
​
export default function AspectRatioShowcase() {
  return (
    <XDSHStack gap={4} vAlign="start">
      <XDSAspectRatio ratio={1} xstyle={[s.square, s.box]}>
        <XDSCenter width="100%" height="100%">
          <XDSText type="supporting" color="secondary">
            1 : 1
          </XDSText>
        </XDSCenter>
      </XDSAspectRatio>
      <XDSAspectRatio ratio={4 / 3} xstyle={[s.fourThree, s.box]}>
        <XDSCenter width="100%" height="100%">
          <XDSText type="supporting" color="secondary">
            4 : 3
          </XDSText>
        </XDSCenter>
      </XDSAspectRatio>
      <XDSAspectRatio ratio={16 / 9} xstyle={[s.widescreen, s.box]}>
        <XDSCenter width="100%" height="100%">
          <XDSText type="supporting" color="secondary">
            16 : 9
          </XDSText>
        </XDSCenter>
      </XDSAspectRatio>
    </XDSHStack>
  );
}