# Input Group

Groups an input with leading/trailing addons — icons, buttons, or text.

- Category: Forms
- Page: https://wunderui.com/components/input-group
- Tier: Free

## Install

```bash
npx wunderui-cli add input-group
```

## Import

```tsx
import { InputGroup, InputGroupAddon, InputGroupCopy, InputGroupCopyProps, InviteLinkRow } from "@/components/ui/input-group"
```

## Minimal usage

Then use it:

```tsx
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.

## Usage

```tsx
import { Mail } from "lucide-react"
import { Field, FieldDescription } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { InputGroup, InputGroupAddon } from "@/components/ui/input-group"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <Field>
      <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>
      <FieldDescription>We send receipts to this address.</FieldDescription>
    </Field>
  )
}
```

## 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

- [Input](https://wunderui.com/components/input) for a plain field with no content inside it
- [Number Field](https://wunderui.com/components/number-field) for a number with its own steppers, limits and formatting
- [Select](https://wunderui.com/components/select) for a choice from a list, also when it sits next to an input
- [Combobox](https://wunderui.com/components/combobox) for a field that filters a list of options as you type

## Keyboard

The group isn't a tab stop. Focus goes to the input and then to each button inside, in the order they are written.

| Key | Action |
|---|---|
| `Tab` or `Shift+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 `aria-pressed`. |

## Behavior

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

- `InputGroup`: 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.
- `InputGroupAddon`: 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.
- `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.
- `IconButton`: 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.
- `InputGroupCopy`: 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.
- `InviteLinkRow`

## Best practices

### When to use

- Use an Input Group when something belongs inside the field's border: an icon, a fixed part of the value or a small action on it. Other actions are buttons beside the field.

### 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.
- 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.
- 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.
- Set aria-invalid and disabled on the input, not on the group. The group reads them and turns the border red or dims itself.
- 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 put a second field or a long text in an addon. An addon is a unit, an icon or a short word.
- 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

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### InputGroupAddon

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### InputGroupCopy

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | string |  | The text shown in the read-only field and put on the clipboard. |
| 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. |
| copiedLabel | string | "Copied" | The label of the button for 1.5 s after a copy. "Copied" by default. |
| copyLabel | string | "Copy" | The label of the button. "Copy" by default. |
| onCopy | (value: string) => void |  | Called with the value once the clipboard took it. |

### InviteLinkRow

| Prop | Type | Default |
|---|---|---|
| link* | string |  |
| className | string |  |
| onCopy | () => void |  |

## Examples

### Addons: icon, prefix, suffix, and prefix with suffix

```tsx
import { Input } from "@/components/ui/input"
import { InputGroup, InputGroupAddon } from "@/components/ui/input-group"
import { Label } from "@/components/ui/label"
import { Mail } from "lucide-react"

export function Example() {
  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>
  )
}
```

### Buttons inside: clear, copy, show or hide, stepper and retry

```tsx
import { useState } from "react"
import { X } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Input } from "@/components/ui/input"
import { InputGroup } from "@/components/ui/input-group"
import { Label } from "@/components/ui/label"

export function Example() {
  const [value, setValue] = useState("Nora Lindgren")

  return (
    <div className="flex flex-col gap-1">
      <Label htmlFor="name" className="mb-1">
        Full name
      </Label>
      <InputGroup className="pr-px">
        <Input id="name" value={value} onChange={(event) => setValue(event.target.value)} />
        {value !== "" && (
          <IconButton variant="ghost" size="sm" aria-label="Clear full name" onClick={() => setValue("")} className="rounded-[calc(var(--radius-md)-0.125rem)]">
            <X />
          </IconButton>
        )}
      </InputGroup>
    </div>
  )
}
```

### Attached action: a button beside the field

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function Example() {
  const [code, setCode] = useState("")

  return (
    <div className="flex flex-col gap-1">
      <Label htmlFor="coupon" className="mb-1">
        Coupon code
      </Label>
      <div className="flex gap-2">
        <Input id="coupon" placeholder="WUNDER20" value={code} onChange={(event) => setCode(event.target.value)} />
        <Button variant="plain" disabled={code.trim() === ""} className="shrink-0">
          Apply
        </Button>
      </div>
    </div>
  )
}
```

### Sizes: 32, 36 and 40 px

```tsx
import { Input } from "@/components/ui/input"
import { InputGroup, InputGroupAddon } from "@/components/ui/input-group"

export function Example() {
  return (
    <InputGroup>
      <InputGroupAddon className="text-sm">https://</InputGroupAddon>
      <Input aria-label="Website" placeholder="wunderui.com" />
    </InputGroup>
  )
}
```

### States: default, hover, focus, filled, disabled, read-only, invalid and loading

```tsx
import { Mail } from "lucide-react"
import { Field, FieldDescription } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { InputGroup, InputGroupAddon } from "@/components/ui/input-group"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <Field>
      <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>
      <FieldDescription>We send receipts to this address.</FieldDescription>
    </Field>
  )
}
```

### Copy field: a read-only value with a Copy button

```tsx
import { InputGroupCopy } from "@wunderui/react"

export function InviteLink() {
  return (
    <InputGroupCopy
      aria-label="Invite link"
      value="https://wunderui.com/invite/a7k2m9"
    />
  )
}
```

## In context

### Domain: a prefix and a suffix around what you type

The fixed parts frame the part the person chooses, and the helper line shows the whole address. Type in the field to see it change.

```tsx
import { useState } from "react"
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { InputGroup, InputGroupAddon } from "@/components/ui/input-group"

export function Example() {
  const [name, setName] = useState("wunderui")

  return (
    <Field>
      <FieldLabel>Workspace address</FieldLabel>
      <InputGroup>
        <InputGroupAddon className="text-sm">https://</InputGroupAddon>
        <Input value={name} onChange={(event) => setName(event.target.value.toLowerCase())} />
        <InputGroupAddon className="text-sm">.wunderui.app</InputGroupAddon>
      </InputGroup>
      <FieldDescription>Your team opens the workspace at https://{name || "name"}.wunderui.app.</FieldDescription>
    </Field>
  )
}
```

### Share link: read-only with a copy button

The field is read-only, so it stays focusable and selectable. The button reports the copy with a check and an updated label for a moment.

```tsx
import { useState } from "react"
import { Copy } from "lucide-react"
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { IconButton } from "@/components/ui/icon-button"
import { Input } from "@/components/ui/input"
import { InputGroup } from "@/components/ui/input-group"

export function Example() {
  const [copied, setCopied] = useState(false)

  return (
    <Field>
      <FieldLabel>Share link</FieldLabel>
      <InputGroup className="bg-bg-subtle pr-px">
        <Input readOnly defaultValue="wunderui.com/share/pr-4k8Zq" />
        <IconButton
          variant="ghost"
          size="sm"
          phase={copied ? "success" : "idle"}
          aria-label={copied ? "Link copied" : "Copy link"}
          onClick={() => {
            void navigator.clipboard.writeText("wunderui.com/share/pr-4k8Zq")
            setCopied(true)
            window.setTimeout(() => setCopied(false), 1600)
          }}
          className="rounded-[calc(var(--radius-md)-0.125rem)]"
        >
          <Copy />
        </IconButton>
      </InputGroup>
      <FieldDescription>Anyone with the link can view the workspace report.</FieldDescription>
    </Field>
  )
}
```

### Quantity: a button on each side

Minus and plus sit inside the field and stop at 1 and 50. The value can be typed as well, and the price under the field follows it.

```tsx
import { useState } from "react"
import { Minus, Plus } from "lucide-react"
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { IconButton } from "@/components/ui/icon-button"
import { Input } from "@/components/ui/input"
import { InputGroup } from "@/components/ui/input-group"

const PRICE = 12

export function Example() {
  const [seats, setSeats] = useState(5)

  return (
    <Field>
      <FieldLabel>Team seats</FieldLabel>
      <InputGroup className="px-px">
        <IconButton variant="ghost" size="sm" aria-label="Fewer seats" disabled={seats <= 1} onClick={() => setSeats(seats - 1)} className="rounded-[calc(var(--radius-md)-0.125rem)]">
          <Minus />
        </IconButton>
        <Input inputMode="numeric" value={seats} onChange={(event) => setSeats(Math.min(50, Math.max(1, Number(event.target.value.replace(/D/g, "")) || 1)))} className="text-center" />
        <IconButton variant="ghost" size="sm" aria-label="More seats" disabled={seats >= 50} onClick={() => setSeats(seats + 1)} className="rounded-[calc(var(--radius-md)-0.125rem)]">
          <Plus />
        </IconButton>
      </InputGroup>
      <FieldDescription>${seats * PRICE}.00 per month at ${PRICE} per seat.</FieldDescription>
    </Field>
  )
}
```

### Search: a shortcut hint that gives way to Clear

While the field is empty, the trailing slot shows the keys that focus it. Once there is a query, it holds a Clear button instead.

```tsx
import { useState } from "react"
import { Search, X } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Input } from "@/components/ui/input"
import { InputGroup, InputGroupAddon } from "@/components/ui/input-group"
import { Kbd, KbdGroup } from "@/components/ui/kbd"

export function Example() {
  const [query, setQuery] = useState("Priya")

  return (
    <InputGroup className="border-border bg-background pr-px">
      <InputGroupAddon>
        <Search aria-hidden />
      </InputGroupAddon>
      <Input
        type="search"
        aria-label="Search members"
        placeholder="Search members"
        value={query}
        onChange={(event) => setQuery(event.target.value)}
        className="placeholder:text-text-tertiary [&::-webkit-search-cancel-button]:hidden"
      />
      {query === "" ? (
        <InputGroupAddon className="pr-2">
          <KbdGroup>
            <Kbd>⌘</Kbd>
            <Kbd>K</Kbd>
          </KbdGroup>
        </InputGroupAddon>
      ) : (
        <IconButton variant="ghost" size="sm" aria-label="Clear search" onClick={() => setQuery("")} className="rounded-[calc(var(--radius-md)-0.125rem)]">
          <X />
        </IconButton>
      )}
    </InputGroup>
  )
}
```

## For AI agents

`get_component("input-group")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
