Native Select

Instalacja#

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

Użycie#

import {
  NativeSelect,
  NativeSelectOptGroup,
  NativeSelectOption,
} from "@/components/ui/native-select"

<NativeSelect defaultValue="yearly">
  <NativeSelectOption value="monthly">Monthly</NativeSelectOption>
  <NativeSelectOption value="yearly">Yearly</NativeSelectOption>
</NativeSelect>

className stylizuje kontener, który domyślnie ma w-fit — aby ustalić szerokość kontrolki, przekaż np. w-full. Wszystkie pozostałe propsy trafiają do elementu <select>.

Przykłady#

Rozmiary#

Rozmiary sm, default i lg mają te same wysokości co Input i Button, więc filtr i powiązana z nim akcja układają się w jednej linii.

Grupy opcji#

NativeSelectOptGroup dodaje do długich list nagłówki, których nie da się wybrać. Systemy operacyjne renderują je natywnie — z wcięciem na komputerach, jako osobne sekcje w mobilnych oknach wyboru.

Nieprawidłowy i wyłączony#

Pusta, wyłączona pierwsza opcja działa jak placeholder: w połączeniu z required przeglądarka nie wyśle formularza, dopóki ktoś nie dokona prawdziwego wyboru. Nieprawidłowy wybór oznacz atrybutem aria-invalid i komunikatem FieldError — dokładnie tak jak w polu tekstowym.

Wytyczne#

Kiedy używać#

• W procesach używanych głównie na urządzeniach mobilnych: telefon otwiera wtedy systemowe okno wyboru, które jest szybsze i dobrze znane.
• W długich formularzach i na stronach renderowanych na serwerze, które muszą działać, zanim załaduje się JavaScript — albo całkiem bez niego.
• W prostych listach opcji tekstowych, w których własne renderowanie niczego nie wnosi.

Kiedy nie używać#

• Gdy opcje potrzebują ikon, opisów lub własnego układu — użyj Select.
• Gdy lista jest na tyle długa, że przydaje się wyszukiwanie — użyj Combobox.
• Gdy od dwóch do pięciu opcji trzeba porównać jednym spojrzeniem — użyj Radio Group lub Toggle Group.

Natywny czy własny?#

Wybierz jedno rozwiązanie dla danego obszaru produktu i trzymaj się go konsekwentnie — oba naraz w jednym formularzu sprawiają wrażenie niedokończonej pracy.

Dostępność#

Native Select to prawdziwy <select>, więc bez jednej linijki skryptu przejmuje z platformy obsługę klawiatury, semantykę dla czytników ekranu i zachowanie w formularzach.

• Nadaj mu etykietę — przez FieldLabel z htmlFor/id albo, w kompaktowych filtrach, przez aria-label.
• Kolory systemowe. Opcje używają kolorów systemowych Canvas i CanvasText, więc w trybie ciemnym rozwinięta lista podąża za systemem operacyjnym i za color-scheme strony.
• Kontrast. Obramowanie korzysta z tokenu input o kontraście 3:1 względem strony; ikona strzałki jest dekoracyjna i ukryta przed technologiami wspomagającymi.

Dokumentacja API#

NativeSelect#

Renderuje kontener <div> z elementem <select> i ikoną strzałki. Przyjmuje wszystkie natywne propsy elementu select.

NativeSelectOption#

Renderuje element <option>. Przyjmuje wszystkie natywne propsy opcji, w tym value i disabled.

NativeSelectOptGroup#

Renderuje element <optgroup>. W label podaj nagłówek grupy.