Alert

Anatomia#

Instalacja#

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

Użycie#

import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"

<Alert variant="warning">
  <TriangleAlertIcon />
  <AlertTitle>Your trial ends in 3 days</AlertTitle>
  <AlertDescription>Add a payment method to keep your projects running.</AlertDescription>
</Alert>

Przykłady#

Warianty#

Pięć wariantów odpowiada skalom statusów. Każdy barwi tło stopniem 2, rysuje obramowanie stopniem 6, a tekstowi nadaje stopnie 11 i 12 — dzięki temu każdy wariant osiąga 4,5:1 w obu trybach bez dodatkowej pracy.

Z akcją#

Umieść jedną akcję uzupełniającą w AlertAction. Znajduje się po prawej stronie, wyśrodkowana w pionie, a alert rezerwuje dla niej miejsce, więc tekst nigdy pod nią nie wchodzi. Ogranicz się do jednego małego przycisku — alert z paskiem narzędzi to już karta.

Z linkiem#

Linki w AlertDescription są podkreślone i dziedziczą kolor tekstu wariantu, więc pozostają czytelne na każdym zabarwionym tle.

Z listą#

Gdy trzeba poprawić kilka rzeczy, wypunktuj je. Listę się przegląda, akapit — tylko przebiega wzrokiem.

Tylko tytuł#

Krótki komunikat nie potrzebuje opisu. Ikona jest opcjonalna — pomiń ją w neutralnych notkach, które nie powinny przyciągać wzroku.

Wytyczne#

Kiedy używać#

• Aby wyjaśnić sytuację, która dotyczy całej strony lub sekcji: awarię, limit, oczekującą weryfikację.
• Aby podsumować błędy formularza nad formularzem — jako uzupełnienie komunikatów o błędach przy poszczególnych polach.
• Aby wyeksponować informację, która musi pozostać widoczna, dopóki sytuacja się nie zmieni.

Kiedy nie używać#

• Do potwierdzania czegoś, co ktoś właśnie zrobił — użyj komponentu Toast. Powiadomienie pojawia się tam, gdzie już skupia się uwaga, i samo znika.
• Do błędów pojedynczego pola — użyj FieldError wewnątrz komponentu Field, tuż przy polu.
• Do decyzji, które blokują dalsze działanie — użyj komponentu Alert Dialog.
• Do treści marketingowych. Alert pożycza pilność od kolorów statusów; marnowanie jej na promocje uczy ludzi, że można go ignorować.

Wybieraj najłagodniejszy wariant, który oddaje sytuację#

Kolory statusów to ograniczony budżet. Jeśli nic złego się nie dzieje, alert ma wariant default lub info — nawet gdy komunikat wydaje się ważny. Zachowaj warning dla rzeczy, które przestaną działać, a destructive dla tych, które już nie działają.

Treść#

• Zaczynaj od skutku, nie od przyczyny: Po osiągnięciu limitu kompilacje trafią do kolejki, a nie Wykorzystano 90% minut kompilacji.
• Powiedz, co dalej. Każde ostrzeżenie i każdy błąd powinny wskazywać akcję albo prowadzić do niej linkiem.
• Ogranicz tytuł do jednego wiersza, a opis do dwóch zdań. Dłuższa treść powinna trafić na osobną stronę.
• Nie piętrz alertów. Dwa lub więcej alertów w jednym miejscu konkurują ze sobą; połącz je albo pokaż najpoważniejszy.

Dostępność#

Alerty są regionami na żywo (live regions), więc ich treść jest ogłaszana w chwili pojawienia się, bez przenoszenia fokusu.

• Pilność ogłoszenia zależy od wagi. destructive i warning renderują role="alert" i są ogłaszane natychmiast, przerywając to, co czytnik ekranu właśnie czytał. Pozostałe warianty renderują role="status" i czekają na przerwę. Przekaż role, aby to nadpisać — na przykład role="note" dla treści statycznej, która w ogóle nie powinna być ogłaszana.
• Wstawiaj, nie odsłaniaj. Regiony na żywo ogłaszają zmiany. Alert obecny od załadowania strony jest odczytywany w kolejności dokumentu; alert dodany później — powiedzmy po nieudanym wysłaniu formularza — jest ogłaszany w chwili pojawienia się.
• Kolor nigdy nie jest jedynym sygnałem. Łącz każdy wariant statusu z ikoną i tytułem, który nazywa status słowami.
• Akcje pozostają w kolejności tabulacji. Przyciski i linki w alercie są osiągalne klawiszem Tab i nigdy nie przejmują fokusu, gdy alert się pojawia.

Dokumentacja API#

Alert#

Kontener. Renderuje <div> z data-slot="alert" i atrybutem data-variant.

AlertTitle#

Pojedynczy wiersz, który wyraża sedno komunikatu. Renderuje <div>; gdy alert ma ikonę, tytuł zaczyna się w drugiej kolumnie.

AlertDescription#

Tekst uzupełniający, linki i listy. Ma kolor stopnia 11 ze skali wariantu.

AlertAction#

Slot na jedną akcję uzupełniającą, przypięty do prawej krawędzi. Gdy akcja jest obecna, alert dodaje odstęp z prawej strony.