Input Group

Stabilny

Pole z dołączonymi ikonami, tekstem, przyciskami lub podpowiedziami klawiszy — z jednym obramowaniem, fokusem i walidacją, jak pojedyncza kontrolka.

Kod źródłowy Rejestr

examples/input-group/demo.tsx

⌘K

Anatomia

https://

1GrupaJedno obramowane pole z własną poświatą fokusu, dzięki czemu dodatki i pole odbiera się jako jedną kontrolkę.
2Dodatek początkowyTekst lub ikona przed polem: protokół, waluta, ikona wyszukiwania. Kliknięcie w dodatek ustawia fokus w polu.
3KontrolkaSamo pole — jedno- lub wielowierszowe — bez obramowania wewnątrz grupy.
4Dodatek końcowyPrzycisk, jednostka lub podpowiedź klawiszowa za polem.

Instalacja

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

Użycie

import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
} from "@/components/ui/input-group"

<InputGroup>
  <InputGroupAddon>
    <SearchIcon />
  </InputGroupAddon>
  <InputGroupInput placeholder="Search…" />
</InputGroup>

Wewnątrz grupy używaj InputGroupInput i InputGroupTextarea — nigdy zwykłego komponentu Input. Obramowanie, wypełnienie, poświata fokusu i stan błędu należą do grupy; wewnętrzna kontrolka jest celowo pozbawiona własnych stylów.

Przykłady

Dodatki tekstowe

Prefiksy i sufiksy niosą jednostki i stałe części wartości — walutę, domenę — dzięki czemu ludzie wpisują tylko to, co się zmienia. Owiń tekst w InputGroupText.

examples/input-group/text-addons.tsx

Przyciski

InputGroupButton to kompaktowy Button w wariancie ghost, dopasowany rozmiarem do wnętrza pola: skopiuj wartość, odsłoń hasło, wyczyść zapytanie. Przyciski z samą ikoną potrzebują aria-label; przełączniki takie jak Pokaż hasło zgłaszają też aria-pressed.

examples/input-group/buttons.tsx

Status

Dodatki mogą informować, co dzieje się z wartością: podczas sprawdzania dostępności pokazują Spinner, a potem potwierdzają wynik ikoną. Zawsze powtórz status tekstem pod polem — sama ikona nie wystarczy.

examples/input-group/status.tsx

Pole wiadomości

Z InputGroupTextarea i dodatkiem block-end grupa staje się polem do pisania wiadomości: pole rośnie razem z tekstem, a załączniki, podpowiedzi i przycisk wysyłania pozostają przypięte pod nim.

examples/input-group/composer.tsx

Enter wysyła · Shift + Enter dodaje nowy wiersz

Dodatki blokowe

Dodatki block-start stoją nad kontrolką na całą szerokość — nazwa pliku nad edytorem kodu, pasek narzędzi nad notatką. Dodaj border-b, żeby je oddzielić.

examples/input-group/block-addon.tsx

webhook-payload.json

Wytyczne

Kiedy używać

Jednostki, prefiksy i sufiksy, które są częścią wartości: $, USD, .prfct.dev, https://.
Akcje działające na samej wartości: kopiowanie, odsłanianie, czyszczenie, wysłanie wyszukiwania.
Sygnały dotyczące wartości: ikona wyszukiwania na początku, status walidacji, podpowiedź skrótu klawiszowego.

Kiedy nie używać

Akcje, które nie dotyczą wartości, takie jak Zapisz czy Anuluj — umieść wtedy Button obok pola.
Więcej niż dwa dodatki po jednej stronie. Zatłoczone pole trudno objąć wzrokiem, a na wpisywanie zostaje mało miejsca.
Wielowierszowa edycja z formatowaniem — użyj dedykowanego edytora.

Dodatki nie mogą udawać

Ikona na początku pola ma wyjaśniać, do czego ono służy, a nie je zdobić. Jeśli jest interaktywna, musi być przyciskiem InputGroupButton z etykietą — ikona, która wygląda na klikalną, a nic nie robi, to pułapka.

.prfct.dev

Dobrze.Dodatki tekstowe niosą stałe części adresu; ludzie wpisują tylko tę, która się zmienia.

Źle.Prośba o pełny adres URL zachęca do literówek w częściach, których nikt nie powinien musieć wpisywać.

Dostępność

Jedna kontrolka, jedna nazwa. Nazwij InputGroupInput przez FieldLabel z htmlFor/id albo przez aria-label. Tekst dodatku, np. USD, nie wchodzi w skład nazwy — jeśli jednostka ma znaczenie, podaj ją w etykiecie lub opisie.
Grupowanie. Grupa i każdy dodatek renderują role="group"; kliknięcie w puste miejsce dodatku ustawia fokus w polu.
Fokus i stan. Gdy kontrolka ma fokus z klawiatury, cała grupa pokazuje poświatę fokusu w kolorze marki, a gdy kontrolka ma aria-invalid — robi się czerwona.
Przyciski. InputGroupButton to prawdziwy przycisk, domyślnie z type="button", więc nigdy przypadkiem nie wyśle formularza.
Skróty. Podpowiedź Kbd jest wyłącznie wizualna. Zadbaj, żeby skrót dało się odkryć także gdzie indziej, np. w podpowiedzi lub na stronie pomocy.

Klawisz	Działanie
`Tab`	Przenosi fokus do pola, a potem na kolejne przyciski w grupie.
`EnterSpacja`	Aktywuje InputGroupButton, który ma fokus.

Dokumentacja API

InputGroup

Renderuje <div role="group">, który rysuje obramowanie, wypełnienie i stan fokusu. Przyjmuje wszystkie propsy div.

InputGroupAddon

Renderuje <div role="group"> na ikony, tekst, przyciski lub podpowiedzi Kbd.

Prop	Typ	Domyślnie
`align` Przed kontrolką lub za nią w tej samej linii albo nad nią lub pod nią na całą szerokość.	`"inline-start" \| "inline-end" \| "block-start" \| "block-end"`	`"inline-start"`

InputGroupButton

Renderuje Button o rozmiarze dopasowanym do grupy. Przyjmuje wszystkie propsy Button; size przyjmuje własne rozmiary grupy, wymienione poniżej.

Prop	Typ	Domyślnie
`size` Wysokość 24 lub 28 px; rozmiary icon-xs i icon-sm są kwadratowe.	`"xs" \| "sm" \| "icon-xs" \| "icon-sm"`	`"xs"`
`variant` Dowolny wariant Button. Dla głównej akcji, np. Wyślij, użyj default.	`Button variant`	`"ghost"`
`type` Domyślnie button, więc przycisk nigdy przypadkiem nie wyśle formularza.	`"button" \| "submit" \| "reset"`	`"button"`