Popover

Instalacja#

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

Użycie#

import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover"

<Popover>
  <PopoverTrigger render={<Button variant="outline" />}>Dimensions</PopoverTrigger>
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle>Dimensions</PopoverTitle>
      <PopoverDescription>Set the size of the selected frame.</PopoverDescription>
    </PopoverHeader>
    {/* … */}
  </PopoverContent>
</Popover>

Za pozycjonowanie popovera odpowiada Floating UI: popover otwiera się pod wyzwalaczem, przeskakuje na drugą stronę, gdy brakuje miejsca, i nie wychodzi poza obszar widoku. Pojawia się od strony wyzwalacza — to choreografia popup-motion, wspólna dla wszystkich pływających powierzchni prfct.

Przykłady#

Szybkie wprowadzanie danych#

Popover może zawierać mały formularz. Steruj nim przez open i onOpenChange, aby zamykał się po udanym wysłaniu, a potwierdzenie pokaż w powiadomieniu Toast.

Nagłówek#

PopoverHeader, PopoverTitle i PopoverDescription nadają popoverowi tytuł, który nazywa go dla technologii wspomagających. Używaj ich zawsze, gdy treść zawiera więcej niż jedną kontrolkę.

Położenie#

side ustawia popover po wybranej stronie wyzwalacza: top, right, bottom (domyślnie) lub left. Jeśli po preferowanej stronie brakuje miejsca, popover przeskakuje na przeciwną.

Wyrównanie#

align wyrównuje popover do początku (start), środka (center, domyślnie) lub końca (end) wyzwalacza. Wyrównanie do początku sprawdza się w menu czytanych od lewej do prawej, a do końca — przy wyzwalaczach blisko prawej krawędzi.

Wytyczne#

Kiedy używać#

• Do kontrolek działających na jednym elemencie: formatowania, wymiarów, filtrów pojedynczej kolumny.
• Do szybkiego wprowadzania danych, które nie wymaga pełnego okna dialogowego: notatki, zmiany nazwy, daty.
• Do wybierania: kolorów, emoji, dat.

Kiedy nie używać#

• Do pokazania zwykłej etykiety tekstowej — użyj Tooltip.
• Do podglądu linku po najechaniu — użyj Hover Card.
• Do listy akcji — użyj Dropdown Menu, które zapewnia nawigację strzałkami i wybór przez wpisywanie.
• Do zadań, które wymagają skupienia i wyraźnego zakończenia — użyj Dialog.

Niech pozostanie mały#

Popover to rzut oka, a nie miejsce docelowe. Jeśli jego treść wymaga przewijania, więcej niż kilku kontrolek albo przycisku Zapisz, wyrosła już z popovera. Trzymaj szerokość poniżej ~20 rem, a wysokość — w granicach kilku wierszy.

Dostępność#

Wyzwalacz to przycisk z aria-expanded i aria-haspopup="dialog"; popup to niemodalne okno dialogowe, którego etykietą jest PopoverTitle, jeśli występuje.

• Domyślnie niemodalny. Strona pozostaje interaktywna; kliknięcie poza popoverem albo przeniesienie fokusu gdzie indziej go zamyka. Przekaż modal, aby uwięzić fokus i zablokować przewijanie, albo modal="trap-focus", aby tylko uwięzić fokus.
• Nazwij go. Używaj PopoverTitle w każdym popoverze z kontrolkami. Jeśli nie ma widocznego tytułu, dodaj aria-label do PopoverContent.
• Otwieranie po najechaniu trzeba włączyć. openOnHover na wyzwalaczu sprawia, że popover otwiera się także po najechaniu, ale zawsze otwiera się też po kliknięciu i z klawiatury — nigdy nie rób z najechania jedynej drogi dostępu.

Dokumentacja API#

Popover#

Komponent główny. Nie renderuje żadnego elementu. Przyjmuje wszystkie propsy Popover.Root z Base UI.

PopoverTrigger#

Otwiera i zamyka popover. Renderuje <button>; użyj render, aby wyrenderować Button z prfct.

PopoverContent#

Renderuje portal, element pozycjonujący i popup.

PopoverHeader, PopoverTitle, PopoverDescription#

PopoverHeader układa tytuł i opis jeden pod drugim. PopoverTitle renderuje <h2>, który jest etykietą popovera; PopoverDescription renderuje <p>, który go opisuje.