# InputGroup

An Input or Textarea with icons, text and buttons inside one box.

```ehtml Example
import {
  InputGroup, InputGroupAddon, InputGroupText, InputGroupButton,
} from "@elements/ui/input-group";
import { Input } from "@elements/ui/input";
import { Icon } from "@elements/ui/icon";

<InputGroup>
  <Input value={state.query} placeholder="Search" attrs={{ "aria-label": "Search" }} />
  <InputGroupAddon><Icon name="search" /></InputGroupAddon>
  <InputGroupAddon align="inline-end">
    <InputGroupButton onclick={() => run(state)}>Search</InputGroupButton>
  </InputGroupAddon>
</InputGroup>
```

## Parts

| Part | What it is |
|---|---|
| `InputGroupAddon` | A region before, after, above or below the control. |
| `InputGroupText` | Muted text or an icon in an addon. |
| `InputGroupButton` | A button sized for the box. |
| `.input-group` | The box: it draws the border, focus ring and invalid state for the control inside. |

## Attributes

### InputGroup

| Attribute | Type | Default | Description |
|---|---|---|---|
| `disabled` | `boolean` | `false` | Disables the control and every button in the group, and dims the addons. Turning it off re-enables only what the group disabled. |
| `class` | `string` | `""` | Extra classes on the box. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | aria-label, data-\* for the box. |

### InputGroupAddon

| Attribute | Type | Default | Description |
|---|---|---|---|
| `align` | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` | Where the addon sits: before, after, above or below the control. |
| `bordered` | `boolean` | `false` | A rule between a block addon and the control. |
| `class` | `string` | `""` | Extra classes. |

### InputGroupButton

| Attribute | Type | Default | Description |
|---|---|---|---|
| `variant` | `"primary" \| "secondary" \| "outline" \| "ghost" \| "link" \| "danger"` | `"ghost"` | Button variant. |
| `size` | `"xs" \| "sm" \| "icon-xs" \| "icon-sm"` | `"xs"` | Sized to fit inside the box. |
| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Form behavior. |
| `label` | `string` | `""` | Accessible name; required for icon sizes. |
| `disabled` | `boolean` | `false` | Native disabled. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Attributes for the `<button>`. |
| `onclick` | `(e: MouseEvent) => void` | `() => {}` | Click handler. |

## Slots

| Slot | Part | Content |
|---|---|---|
| `default` | `InputGroup` | An `<Input>` or `<Textarea>` (or an element with data-slot="input-group-control"), then addons. |
| `default` | `InputGroupAddon` | Icons, InputGroupText, InputGroupButton, `<kbd>`. |

## Keyboard

| Keys | Action |
|---|---|
| `Tab` | The control first, then the buttons in the addons, in markup order. |
| `Click on an addon` | Focuses the control (not when the click is on a button). |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-align` | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | addon |
| `data-disabled` | present while disabled | group |
| `data-size` | `"xs" \| "sm" \| "icon-xs" \| "icon-sm"` | button |

## Accessibility

- The box and each addon are role="group"; label the control itself (aria-label, a Label, or a Field around the group).
- Put addons after the control in the markup so focus reaches the input before its buttons; align places them visually.
- The focus ring and invalid border are drawn on the box from the control's own focus and aria-invalid.
- Icon-only buttons need label.

## See also

- [Input](input): A native text input in the theme's control chrome, with a two-way value.
- [Icon](icon): An inline stroke icon from the set the templates draw their own controls with, sized in pixels and colored by the text around it.
- [ButtonGroup](button-group): Related buttons, or an input and its buttons, joined into one control.
- [Textarea](textarea): A native multi-line input that grows with its content, between rows and maxRows.
- [Field](field): A label, a control, a description and an error wired together, with native validation that never moves the layout.
- [Label](label): A native label for a control, which dims when the control is disabled.