Tooltip
StabilnyKrótka etykieta tekstowa, która pojawia się po najechaniu i przy fokusie z klawiatury, żeby nazwać kontrolkę z samą ikoną albo pokazać jej skrót.
Instalacja
$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/tooltip.jsonOwiń aplikację jeden raz w TooltipProvider. Nadaje on wszystkim podpowiedziom to samo opóźnienie i sprawia, że gdy jedna jest już widoczna, sąsiednie otwierają się od razu — przesuń kursor wzdłuż paska narzędzi, a etykiety pojawią się bez czekania.
import { TooltipProvider } from "@/components/ui/tooltip"
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<TooltipProvider delay={400}>{children}</TooltipProvider>
</body>
</html>
)
}Użycie
import {
Tooltip,
TooltipContent,
TooltipTrigger,
} from "@/components/ui/tooltip"<Tooltip>
<TooltipTrigger render={<Button variant="outline" size="icon" aria-label="Add to library" />}>
<PlusIcon />
</TooltipTrigger>
<TooltipContent>Add to library</TooltipContent>
</Tooltip>Podpowiedzi prfct mają odwrócone kolory — tło gray-12, tekst gray-1 — więc w obu trybach czyta się je jak etykietę nałożoną na dowolną powierzchnię. Pojawiają się też szybciej niż inne wyskakujące elementy (160 ms), bo w ciągu jednej sesji wyświetlają się dziesiątki razy.
Przykłady
Skróty klawiszowe
Podpowiedź to naturalne miejsce na naukę skrótów. Umieść Kbd po etykiecie — sam dopasuje wygląd do odwróconej powierzchni. Przesuń kursor wzdłuż paska narzędzi: gdy otworzy się pierwsza podpowiedź, kolejne pojawiają się natychmiast.
Położenie
side umieszcza podpowiedź nad wyzwalaczem (top, domyślnie), po jego prawej stronie (right), pod nim (bottom) lub po lewej (left). Przy krawędziach widocznego obszaru podpowiedź sama przenosi się na przeciwną stronę.
Wyłączone wyzwalacze
Wyłączony przycisk nie odbiera zdarzeń wskaźnika ani fokusu, więc podpowiedź na nim nigdy by się nie otworzyła. Zachowaj do niego dostęp przez focusableWhenDisabled i wyjaśnij w podpowiedzi, czego brakuje.
Opóźnienie
Provider ustawia opóźnienie 400 ms dla wszystkich podpowiedzi. Nadpisz je dla konkretnego wyzwalacza przez delay — krótsze w gęstych narzędziach, które przegląda się szybko, dłuższe tam, gdzie przypadkowe podpowiedzi by przeszkadzały.
Wytyczne
Kiedy używać
- Do nazywania przycisków z samą ikoną. Każdy przycisk z ikoną potrzebuje
aria-label; podpowiedź pokazuje ten sam tekst widzącym osobom, które korzystają z kursora. - Do pokazywania skrótów klawiszowych częstych akcji.
- Do rozwinięcia uciętego tekstu, na przykład długiej nazwy pliku.
Kiedy nie używać
- Do informacji potrzebnych do wykonania zadania — pokaż je na stronie. Podpowiedzi są niewidoczne, dopóki ktoś nie wpadnie na to, żeby ich poszukać.
- Do treści interaktywnych: linków, przycisków, pól. Podpowiedź znika, gdy kursor się oddali — użyj Popover.
- Do rozbudowanych podglądów — użyj Hover Card.
- W interfejsach wyłącznie dotykowych, gdzie nie ma najechania — zamiast tego pokaż etykietę na stałe.
Pisz etykiety, nie zdania
Podpowiedź czyta się w mgnieniu oka: dwa do czterech słów, wielka litera tylko na początku, bez kropki na końcu. Opisz akcję, nie ikonę.
Dostępność
Podpowiedź to wizualna wskazówka dla widzących osób korzystających z kursora i klawiatury. Otwiera się po najechaniu i przy fokusie z klawiatury, a sama nigdy nie przejmuje fokusu — ale Base UI nie wiąże jej z wyzwalaczem przez aria-describedby, więc czytniki ekranu jej nie odczytują. Znaczenie musi nieść dostępna nazwa samego wyzwalacza.
| Klawisz | Działanie |
|---|---|
Tab | Ustawienie fokusu na wyzwalaczu otwiera podpowiedź po upływie opóźnienia. |
Esc | Zamyka podpowiedź bez przenoszenia fokusu. |
- Umieść etykietę w dostępnej nazwie. Nadaj wyzwalaczom z samą ikoną
aria-labelo tej samej treści co podpowiedź. Podpowiedź uzupełnia nazwę — nigdy jej nie zastępuje. - Można na nią najechać. Przesunięcie kursora na podpowiedź nie zamyka jej, więc osoby korzystające z lupy ekranowej mogą ją przeczytać (WCAG 1.4.13).
disableHoverablePopupustawiaj tylko dla podpowiedzi, które podążają za kursorem. - Można ją zamknąć. Esc ukrywa ją bez przesuwania kursora ani fokusu.
- Tylko zwykły tekst. Treść podpowiedzi jest nieosiągalna z klawiatury; nigdy nie umieszczaj w niej linków ani przycisków.
Dokumentacja API
TooltipProvider
Współdzieli opóźnienie między podpowiedziami. Nie renderuje żadnego elementu.
Tooltip
Komponent główny. Nie renderuje żadnego elementu. Przyjmuje wszystkie propsy Tooltip.Root z Base UI.
TooltipTrigger
Element, który pokazuje podpowiedź. Renderuje <button>; użyj render, żeby wyrenderować Button z prfct.
TooltipContent
Renderuje portal, element pozycjonujący i odwrócony dymek ze strzałką.