AspectRatio

어떤 너비를 받아도 비율을 지키는 상자입니다. 스스로는 아무것도 그리지 않고, 자리를 잡아 두고 그 안의 것을 형태에 붙잡아 둡니다.

import { AspectRatio } from 'neba';

<AspectRatio ratio={16 / 9} rounded>
  <img src={src} alt="동틀 녘의 잔잔한 호수" />
</AspectRatio>;

Props

Prop	타입	기본값	설명
ratio	number | string	1	상자가 지키는 비율. CSS가 쓰는 그대로, 숫자(1.5)나 비('16 / 9')가 aspect-ratio에 그대로 전달됩니다
fit	'cover' | 'contain' | 'fill' | 'none'	'cover'	안의 미디어를 상자에 맞추는 방식. 직계 자식인 img, video, canvas, svg, iframe에 적용되며 그 밖의 것은 평소대로 배치됩니다
rounded	boolean	false	모서리를 size 단계의 반경 사다리로 깎습니다. 레이아웃 컴포넌트는 아무것도 그리지 않으므로 기본은 꺼짐입니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	rounded가 쓰는 반경 사다리의 단계. Box에서처럼 높이도 타입 스케일도 건드리지 않습니다
render	useRender.RenderProp	—	div 대신 다른 요소로 렌더링합니다 (render={<figure />}). Base UI의 render prop 그대로
children	ReactNode	—	비율 안에 담기는 것

<div>의 기본 속성은 그대로 전달되며, render로 요소를 바꿀 수 있습니다. 공통 축은 prop 규칙에서 설명합니다.

예시

ratio

ratio는 CSS의 aspect-ratio 그 자체입니다. 숫자(1.5)든 비('16 / 9')든 손대지 않고 그대로 전달되므로 옮겨 적을 것이 없습니다.

import { AspectRatio } from 'neba';

const RATIOS: Array<{ label: string; ratio: string }> = [
  { label: '1 / 1', ratio: '1 / 1' },
  { label: '4 / 3', ratio: '4 / 3' },
  { label: '16 / 9', ratio: '16 / 9' },
  { label: '21 / 9', ratio: '21 / 9' }
];

export default function AspectRatioRatios() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-2 gap-4 sm:grid-cols-4">
      {RATIOS.map(({ label, ratio }) => (
        <div key={label} className="flex flex-col gap-2">
          <AspectRatio
            ratio={ratio}
            rounded
            className="border border-(--neba-border) bg-(--neba-panel-hover)"
          >
            <div className="flex size-full items-center justify-center text-[0.75rem] text-(--neba-muted-fg)">
              {label}
            </div>
          </AspectRatio>
        </div>
      ))}
    </div>
  );
}

fit

fit은 직계 자식인 미디어 하나(img, video, canvas, svg, iframe)에 적용되는 object-fit입니다. 미디어는 먼저 상자에 맞게 늘어나는데, 이 컴포넌트를 쓸 때마다 반드시 먼저 쓰게 되는 선언 두 줄이 바로 그것입니다. cover는 잘라내고, contain은 여백을 남기며, fill은 찌그러뜨립니다.

import { AspectRatio, type NebaAspectFit } from 'neba';

const FITS: NebaAspectFit[] = ['cover', 'contain', 'fill'];

export default function AspectRatioFit() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-1 gap-4 sm:grid-cols-3">
      {FITS.map((fit) => (
        <div key={fit} className="flex flex-col gap-2">
          <span className="text-[0.75rem] text-(--neba-muted-fg)">{fit}</span>
          {/* The source is 2:3 and the box is square, so each value has to give
              something up: `cover` crops, `contain` letterboxes, `fill` squashes. */}
          <AspectRatio ratio={1} fit={fit} rounded className="bg-(--neba-panel-hover)">
            <img
              src="/samples/photos/red-umbrella-autumn-path.jpg"
              alt="A red umbrella lying on a wet path of fallen leaves"
            />
          </AspectRatio>
        </div>
      ))}
    </div>
  );
}

자리 잡아 두기

내용이 도착했든 아니든 비율은 그대로이므로, AspectRatio 안의 Skeleton은 이미지가 차지할 바로 그 상자를 차지합니다. 이미지가 로드되어도 아래의 무엇도 움직이지 않습니다.

import { useState } from 'react';
import { AspectRatio, Button, Card, Skeleton } from 'neba';

export default function AspectRatioReserving() {
  const [loaded, setLoaded] = useState(false);

  return (
    <div className="flex w-full max-w-80 flex-col gap-3">
      {/* The box is the same height either way, so the card does not jump when
          the image arrives and nothing below it moves under the reader. */}
      <Card title="Alpine lake, dawn" subtitle="Uploaded 4 minutes ago">
        <AspectRatio ratio={16 / 9} rounded>
          {loaded ? (
            <img
              src="/samples/photos/alpine-lake-dawn.jpg"
              alt="A still alpine lake with the first light on the far ridge"
            />
          ) : (
            <Skeleton shape="rect" className="size-full" label="Loading the photograph" />
          )}
        </AspectRatio>
      </Card>

      <Button size="sm" variant="outline" onClick={() => setLoaded((value) => !value)}>
        {loaded ? 'Unload the image' : 'Load the image'}
      </Button>
    </div>
  );
}

rounded

rounded는 size 단계의 반경 사다리로 모서리를 깎습니다. 레이아웃 컴포넌트는 아무것도 그리지 않으므로 기본은 꺼짐이며, 이것이 유일한 예외입니다. 카드 안의 사진은 거의 언제나 이것을 원하기 때문입니다.

<AspectRatio ratio={4 / 3} rounded size="lg">
  <img src={src} alt="" />
</AspectRatio>

접근성

• 이 상자는 role도 이름도 더하지 않습니다. 형태일 뿐이고, 읽히는 것은 그 안에 든 것입니다.
• 안의 img에는 여전히 자기 alt가 필요합니다. 장식용 이미지는 alt=""를 씁니다.