Avatar

Anatomia#

Instalacja#

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

Użycie#

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"

<Avatar>
  <AvatarImage src="/avatars/maya.png" alt="Maya Chen" />
  <AvatarFallback>MC</AvatarFallback>
</Avatar>

Zawsze dodawaj AvatarFallback. Renderuje się podczas ładowania obrazu, a na stałe — gdy obrazu brak lub nie udało się go wczytać. Dzięki temu wolna sieć czy usunięty plik nigdy nie zostawią dziury w układzie.

Przykłady#

Rozmiary#

Pięć rozmiarów podąża za skalą kontrolek: xs 20, sm 24, default 32, lg 40 i xl 56 pikseli. Inicjały skalują się razem z awatarem, więc pozostają optycznie wyśrodkowane.

Treść zastępcza#

Gdy nie ma obrazu, pokaż dwa inicjały wielkimi literami — imienia i nazwiska. Dla osób, o których nic nie wiesz, użyj neutralnej ikony i nadaj jej dostępną nazwę.

Kształt#

Koła są dla osób, zaokrąglone kwadraty — dla tego, do czego osoby należą: przestrzeni roboczych, organizacji, aplikacji. Kształt niesie znaczenie, więc stosuj go konsekwentnie w całym produkcie.

Status#

AvatarBadge znajduje się na prawej dolnej krawędzi i ma obwódkę w kolorze strony, więc jest czytelny na każdym tle. Domyślnie ma kolor sukcesu, oznaczający status online; dla innych stanów zmień kolor tokenem semantycznym i zawsze dodaj etykietę tekstową dla czytników ekranu.

Grupa#

Nakładaj awatary na siebie, aby pokazać, kto bierze udział, bez wymieniania wszystkich. Pokaż od trzech do pięciu, a resztę podsumuj za pomocą AvatarGroupCount. Każdy awatar dostaje obwódkę w kolorze strony, więc miejsca, w których się nakładają, pozostają wyraźne.

Z tekstem#

Zwykle awatar występuje obok imienia i nazwiska. Skoro nazwa jest już widoczna, awatar pełni funkcję dekoracyjną: nadaj obrazowi pusty alt, żeby technologie wspomagające nie odczytywały nazwy dwa razy.

Wytyczne#

Kiedy używać#

• Aby pomóc rozpoznać, kto coś zrobił: autorów komentarzy, osoby przypisane, współpracowników, właścicieli kont.
• Aby oznaczyć przestrzeń roboczą, organizację lub połączoną aplikację w przełącznikach i na listach.

Kiedy nie używać#

• Do grafik dekoracyjnych lub redakcyjnych — użyj zwykłego obrazu.
• Do obiektów, które nie są osobami ani organizacjami, na przykład plików czy integracji na liście — użyj komponentu Item z ikoną.
• Jako jedynego sposobu identyfikacji osoby w gęstej tabeli. Dodaj obok imię i nazwisko albo udostępnij je w podpowiedzi.

Spójna tożsamość#

Inicjały#

Obrazy#

• Używaj kwadratowych obrazów źródłowych co najmniej dwa razy większych od wyświetlanego rozmiaru (112 px dla xl), żeby awatary pozostały ostre na ekranach o dużej gęstości pikseli.
• Kadruj wokół twarzy lub logo; awatar stosuje object-cover i przycina obraz do swojego kształtu.
• Nie dodawaj obramowań — każdy awatar ma już cienką wewnętrzną obwódkę, dzięki której jasne obrazy nie zlewają się z jasnymi powierzchniami.

Dostępność#

• Nazwij obraz. AvatarImage renderuje <img>: ustaw w alt nazwę osoby lub organizacji. Gdy nazwa jest widoczna obok awatara, ustaw alt="" i dodaj aria-hidden do Avatar, żeby inicjały nie były odczytywane jako pojedyncze litery.
• Status wymaga słów. Odznaka to tylko kolor i położenie. Umieść w niej etykietę ukrytą wizualnie (<span className="sr-only">Online</span>), a obecność pokazuj tekstem wszędzie tam, gdzie ma to znaczenie.
• Grupa wymaga podsumowania. Nadaj AvatarGroup atrybut aria-label, który wymienia osoby lub podaje ich liczbę — „Członkowie projektu: Maya Chen, Jonah Okafor i 12 innych osób”.
• Kontrast. Inicjały zastępcze (gray-11 na gray-4) osiągają 4,5:1 w obu trybach.

Dokumentacja API#

Avatar#

Komponent główny. Przyjmuje wszystkie propsy Avatar Root z Base UI.

AvatarImage#

AvatarFallback#

AvatarBadge#

<span> umieszczony na krawędzi awatara. Domyślnie ma kolor sukcesu; zmień go tokenem tła, np. bg-warning-9. Rozmiar ikon wewnątrz jest dobierany automatycznie.

AvatarGroup#

<div>, który nakłada awatary na siebie i otacza je obwódką w kolorze strony. Przyjmuje wszystkie propsy elementu div, w tym aria-label.

AvatarGroupCount#

<div> z podsumowaniem „+N” na końcu grupy. Automatycznie przyjmuje rozmiar awatarów w grupie.