Input Group
FreePut an icon, a unit, a shortcut or a small button inside the border of a field, so they read as one control.
npx wunderui-cli add input-groupPlayground
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
Leave out the protocol.
Leave out the protocol.
Leave out the protocol.
At least 8 characters.
At least 8 characters.
At least 8 characters.
Installation
npx wunderui-cli add input-groupWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
InputGroup,
InputGroupAddon,
InputGroupCopy,
} from "@/components/ui/input-group"
import type { InputGroupCopyProps } from "@/components/ui/input-group"Then use it:
import { Mail } from "lucide-react"
import { Input } from "@/components/ui/input"
import { InputGroup, InputGroupAddon } from "@/components/ui/input-group"
import { Label } from "@/components/ui/label"
export function Email() {
return (
<div className="flex flex-col gap-1">
<Label htmlFor="email" className="mb-1">
Work email
</Label>
<InputGroup>
<InputGroupAddon>
<Mail aria-hidden />
</InputGroupAddon>
<Input id="email" type="email" placeholder="name@company.com" />
</InputGroup>
</div>
)
}Expected result: You see the label Work email above one white field with a grey mail icon at its start and a grey placeholder. Clicking the label focuses the input, and the whole field turns indigo with a ring.
When to use
Use Input Group for
- A field with an icon, a prefix or a unit, such as a search field, https:// or USD
- A small action on the value: clear, copy, show or hide, a stepper, retry
- A shortcut hint at the end of a field
Use something else for
- Input for a plain field with no content inside it
- Number Field for a number with its own steppers, limits and formatting
- Select for a choice from a list, also when it sits next to an input
- Combobox for a field that filters a list of options as you type
Addons
An addon is a slot before or after the value: an icon, a short text like https:// or USD, or both. The group draws the border so addon and field read as one control, and an addon is not interactive.
Buttons inside
A button inside the group acts on the value: clear, copy, reveal, step or retry. It is a 32 px IconButton with 2 px of air and a 6 px corner inside the group's 8 px corner.
At least 8 characters.
Attached action
An action that is not about the value, such as Apply or Send, is its own button beside the field, 8 px away, at the same height. Keep it outside the group so it has its own border, hover and focus.
Sizes
Three heights that match the three smaller Button sizes. The group takes its height from a class on the group, not from the input inside it.
States
Hover and focus are real states of the group: move the pointer over a field, or press Tab. The group draws the border and ring, and a wrong value turns both red while the fill stays white.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
Copy field
InputGroupCopy is the group assembled for a value people copy, such as an invite link or a key: a read-only input with a Copy button inside it. The button turns into a check with Copied for 1.5 s once the clipboard took the text, and a polite live region says so. It replaces InviteLinkRow.
Keyboard interactions
The group isn't a tab stop. Focus goes to the input and then to each button inside, in the order they are written.
- TaborShift+Tab
- Moves into the input, then to each button inside the group, then on. A disabled input and its buttons are skipped. The frame draws the ring while the input has focus.
- Enter
- In the input, sends the form that holds it. On a button, presses it.
- Space
- Presses a focused button, such as show or hide, and toggles its .
Behavior and motion
What the group does itself, and what it leaves to the page.
- The frame draws the border
- The group owns the border, white fill and corner. A direct child input is made transparent and borderless, so the addons sit flush inside one box.
- Hover and focus
- The border darkens when the pointer is over the group. When the input has keyboard focus, the group border turns indigo with a 2 px ring; clicking an addon doesn't focus the input.
- Invalid
- An input marked invalid turns the border red, and the ring turns red on focus. The fill stays white, and the message is yours to write in an error under the group.
- Disabled and read-only
- A disabled input dims the group to 40 % and blocks the pointer. Read-only does neither, so give the group a subtle fill to look read-only; it stays focusable and copyable.
- Height and size
- The group is 36 px tall at the default density. Use the small or large field height for 32 or 40 px; in comfortable density the same tokens give 36, 44 and 52 px.
- Addons
- An addon is a flex slot that keeps its size, with tertiary text and 16 px icons. It has no hover or press state, so use an IconButton for an action.
- Buttons inside
- A 32 px ghost IconButton fits inside the 36 px group with 2 px of air and a 6 px corner (the group's 8 px minus that gap). Trim the group's padding on that side so the air is even.
- Loading
- There is no loading prop. Put a Spinner in a trailing addon, set aria-busy on the input and keep it editable, so a background check never blocks typing.
- Motion
- The border colour changes quickly when the pointer enters or the input takes focus. Nothing moves or scales.
- Reduced motion
- With reduced motion the border colour change stays as a short fade, and a spinner in an addon stops turning.
Anatomy
Input Group is the frame. It draws the border, hover colour and focus ring around one input and its addons, so an icon, a unit or a small button reads as part of the field.
- 1data-slot="input-group"
The bordered frame: 1 px border, 8 px corner, white fill, 36 px high. It owns the hover border, the focus ring and the red invalid border, so the input inside loses its own.
- 2data-slot="input-group-addon"Optional
An icon or short text before the value, such as a search icon, a mail icon or https://. It isn't interactive, uses the tertiary text colour and keeps icons at 16 px.
- 3data-slot="input"
The field itself: a plain Input or any native input as a direct child. It fills the remaining space with no border, fill or padding of its own, and the frame reads its invalid and disabled state.
- 4data-slot="icon-button"Optional
A unit, shortcut or button after the value: USD, a key hint, show or hide, clear, copy. A button here is a 32 px IconButton set 2 px inside the frame with a 6 px corner, concentric with the group.
- data-slot="input-group-copy"Optional
The ready-made copy field: a read-only input and a Copy button inside one group. The button turns into a check with Copied for 1.5 s and a polite live region says so. It replaces InviteLinkRow.
- Optional
Best practices
- Do
Put the input as a direct child of the group. The group styles direct child inputs and can't reach one wrapped in another element.
- Do
Keep the corners concentric. A 32 px IconButton in a 36 px group sits 2 px inside the border, so give it a 6 px corner and trim the group's padding on that side.
- Do
Name the button with aria-label and use aria-pressed for a toggle such as show or hide. An icon alone is not a name.
- Do
Set aria-invalid and disabled on the input, not on the group. The group reads them and turns the border red or dims itself.
- Do
For the other sizes, give the group a height class for the small or large field height. The inner button stays 32 px, so use it in the default and large sizes.
- Don’t
Don't put the main action of a form inside the field. Apply, Send and Subscribe are buttons of their own, next to the field.
- Don’t
Don't put a second field or a long text in an addon. An addon is a unit, an icon or a short word.
- Don’t
Don't rely on the addon text for the field's name. https:// is part of the value; the field still needs a Label.
API reference
InputGroup and InputGroupAddon render a native div, take its attributes and a ref, and add no props. Pass a class to size the group, round a button inside it or give it a fill. InputGroupCopy is the ready-made copy field and takes the props listed under it.
The bordered frame: 1 px border, 8 px corner, white fill, 36 px high. It owns the hover border, the focus ring and the red invalid border, so the input inside loses its own.
An icon or short text before the value, such as a search icon, a mail icon or https://. It isn't interactive, uses the tertiary text colour and keeps icons at 16 px.
The ready-made copy field: a read-only input and a Copy button inside one group. The button turns into a check with Copied for 1.5 s and a polite live region says so. It replaces InviteLinkRow.
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | string | — | The text shown in the read-only field and put on the clipboard. |
| onCopy | (value) => void | — | Called with the value once the clipboard took it. |
| copyLabel | string | "Copy" | The label of the button. "Copy" by default. |
| copiedLabel | string | "Copied" | The label of the button for 1.5 s after a copy. "Copied" by default. |
| aria-label | string | — | Names the read-only field. "Copy value" by default; say what is in it, such as Invite link. |
| className | string | — | Extra classes on the group. |
| Prop | Type | Default | Description |
|---|---|---|---|
| link required | string | — | |
| onCopy | () => void | — |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("input-group")npx wunderui-cli add input-groupThe full library index for assistants is at /llms.txt.