Aspect Ratio

Instalacja#

$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/aspect-ratio.json

Użycie#

import { AspectRatio } from "@/components/ui/aspect-ratio"

<AspectRatio ratio={16 / 9} className="overflow-hidden rounded-xl">
  <img src="/cover.jpg" alt="…" className="size-full object-cover" />
</AspectRatio>

ratio to szerokość podzielona przez wysokość. Komponent to pozycjonowany <div>, którego rozmiar wyznacza właściwość CSS aspect-ratio — bez JavaScriptu i bez sztuczek z paddingiem — więc działa w komponentach serwerowych, a układ nigdy nie przeskakuje po hydratacji.

Przykłady#

Popularne proporcje#

Dobierz proporcje do treści, a potem trzymaj się ich w całej kolekcji, żeby siatki były równe.

Z Next.js Image#

Użyj fill, aby obraz przyjął rozmiar ramki, i object-cover, aby go kadrować zamiast rozciągać. Przekaż sizes, żeby przeglądarka pobrała odpowiednią rozdzielczość.

import Image from "next/image"

<AspectRatio ratio={16 / 9} className="overflow-hidden rounded-xl bg-muted">
  <Image
    src="/showcase/dashboard.png"
    alt="The analytics dashboard in dark mode"
    fill
    sizes="(min-width: 768px) 50vw, 100vw"
    className="object-cover"
  />
</AspectRatio>

Wideo#

Wideo i osadzone treści powinny zarezerwować swoją ramkę, zanim się załadują. Kontrolki i metadane nakładaj za pomocą pozycjonowania absolutnego — ramka ma już relative.

<AspectRatio ratio={16 / 9} className="overflow-hidden rounded-xl">
  <iframe
    src="https://www.youtube-nocookie.com/embed/…"
    title="Designing with tokens"
    allow="accelerometer; encrypted-media; picture-in-picture"
    allowFullScreen
    className="absolute inset-0 size-full"
  />
</AspectRatio>

Kwadratowa siatka#

Proporcje 1:1 sprawiają, że awatary, zdjęcia produktów i miniatury wyglądają jednolicie, nawet gdy obrazy źródłowe nie są jednolite.

Media w karcie#

Umieść ramkę z proporcjami na początku karty i dodaj karcie pt-0 — media wypełnią ją od krawędzi do krawędzi, z zachowaniem zaokrąglonych narożników karty.

Wytyczne#

Kiedy używać#

• Do obrazów, wideo, map i osadzonych treści, których kontener zmienia szerokość wraz z układem.
• W siatkach i karuzelach — aby każdy kafelek miał ten sam kształt.
• Wszędzie tam, gdzie wczytywane z opóźnieniem media spychałyby treść w dół.

Kiedy nie używać#

• Do tekstu lub interfejsu, którego wysokość zależy od treści — sztywne proporcje utną zawartość albo zostawią puste miejsce.
• Gdy kontener ma już stałe wymiary w pikselach — ustaw je bezpośrednio.

Kadruj, nie zniekształcaj#

Media w ramce z proporcjami powinny używać object-cover (kadrowanie z wypełnieniem ramki) lub object-contain (wpasowanie z pustymi pasami), nigdy domyślnego rozciągania.

Dostępność#

Aspect Ratio pełni wyłącznie funkcję prezentacyjną; liczą się media w jego wnętrzu.

• Obrazy potrzebują tekstu alt, który mówi, co przedstawiają, albo alt="", gdy są dekoracyjne.
• Wideo potrzebuje napisów, a osadzone treści — atrybutu title, który nazywa zawartość.
• Stabilny układ. Zarezerwowane miejsce sprawia, że treść nie skacze podczas wczytywania mediów. To pomaga wszystkim — a zwłaszcza osobom, które korzystają z powiększenia lub czytają wolniej.

Dokumentacja API#

AspectRatio#

Renderuje <div> z position: relative i aspect-ratio ustawionym na podstawie ratio. Przyjmuje wszystkie propsy elementu <div>.