# Input components

> Build controlled native buttons, fields, toggles, pickers, and editors.

Canonical: https://natui.dev/docs/components/inputs

NatUI inputs are controlled React components. Pass the current `value` and update it in the corresponding event handler.

## Button [#button]

### ButtonProps


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | No |  |
| `onPress` | `(() => void) \| undefined` | No |  |
| `variant` | `"automatic" \| "bordered" \| "prominent" \| "plain" \| "link" \| undefined` | No |  |
| `role` | `"destructive" \| "cancel" \| undefined` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<Button variant="prominent" onPress={save}>Save</Button>
```

Variants are `automatic`, `bordered`, `prominent`, `plain`, and `link`. Roles are `destructive` and `cancel`. Windows currently renders `bordered`, `plain`, and `link` with its default button style.

## TextField [#textfield]

### TextFieldProps


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string` | Yes |  |
| `placeholder` | `string \| undefined` | No |  |
| `secure` | `boolean \| undefined` | No |  |
| `onChange` | `((value: string) => void) \| undefined` | No |  |
| `onSubmit` | `((value: string) => void) \| undefined` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<TextField
  value={email}
  placeholder="Email"
  onChange={setEmail}
  onSubmit={submit}
/>
```

Set `secure` for protected entry. On Windows, changing `secure` after creation is not supported.

## Toggle [#toggle]

### ToggleProps


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | No |  |
| `value` | `boolean` | Yes |  |
| `style` | `"automatic" \| "checkbox" \| "switch" \| undefined` | No | 'automatic' is the platform default (checkbox on macOS, checkbox on Windows). |
| `onChange` | `((value: boolean) => void) \| undefined` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<Toggle value={enabled} style="switch" onChange={setEnabled}>
  Notifications
</Toggle>
```

Styles are `automatic`, `checkbox`, and `switch`. Changing style after creation is not supported on Windows.

## Slider [#slider]

### SliderProps


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `number` | Yes |  |
| `min` | `number \| undefined` | No |  |
| `max` | `number \| undefined` | No |  |
| `step` | `number \| undefined` | No |  |
| `onChange` | `((value: number) => void) \| undefined` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<Slider value={volume} min={0} max={100} step={1} onChange={setVolume} />
```

## Picker [#picker]

### PickerProps


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string` | Yes |  |
| `options` | `PickerOption[]` | Yes |  |
| `label` | `string \| undefined` | No |  |
| `style` | `"automatic" \| "menu" \| "segmented" \| "radioGroup" \| undefined` | No | 'automatic' is the platform default (a dropdown menu). |
| `onChange` | `((value: string) => void) \| undefined` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<Picker
  label="Size"
  value={size}
  options={[
    { value: 's', label: 'Small' },
    { value: 'm', label: 'Medium' },
  ]}
  style="segmented"
  onChange={setSize}
/>
```

Styles are `automatic`, `menu`, `segmented`, and `radioGroup`. Changing style after creation is not supported on Windows.

## SearchField [#searchfield]

Provides controlled text with optional `placeholder`, `onChange`, and `onSubmit`.

### SearchFieldProps


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string` | Yes |  |
| `placeholder` | `string \| undefined` | No |  |
| `onChange` | `((value: string) => void) \| undefined` | No |  |
| `onSubmit` | `((value: string) => void) \| undefined` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<SearchField value={query} placeholder="Search" onChange={setQuery} />
```

## DatePicker [#datepicker]

Uses a local ISO value without a time zone:

### DatePickerProps

Date/time input. `value` is a LOCAL ISO string without a zone, shaped by
`displayedComponents`: 'YYYY-MM-DD' (date), 'HH:mm' (time), or
'YYYY-MM-DDTHH:mm' (dateTime). Hosts re-serialize canonically so a
round-trip is byte-identical.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string` | Yes |  |
| `displayedComponents` | `"date" \| "time" \| "dateTime" \| undefined` | No |  |
| `onChange` | `((value: string) => void) \| undefined` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

* `date`: `YYYY-MM-DD`
* `time`: `HH:mm`
* `dateTime`: `YYYY-MM-DDTHH:mm`

```tsx
<DatePicker value={due} displayedComponents="date" onChange={setDue} />
```

Windows currently uses a date-only control. A `dateTime` value is accepted, displays its date portion, and emits `YYYY-MM-DD`. A `time` value in `HH:mm` form cannot be parsed by that control, so it leaves the current native date unchanged and cannot emit a time-only value.

## Stepper [#stepper]

### StepperProps


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `number` | Yes |  |
| `min` | `number \| undefined` | No |  |
| `max` | `number \| undefined` | No |  |
| `step` | `number \| undefined` | No |  |
| `onChange` | `((value: number) => void) \| undefined` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<Stepper value={quantity} min={1} max={10} step={1} onChange={setQuantity} />
```

## TextEditor [#texteditor]

Renders a multiline plain-text editor.

### TextEditorProps

Multiline plain-text editor.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string` | Yes |  |
| `onChange` | `((value: string) => void) \| undefined` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<TextEditor value={notes} onChange={setNotes} frame={{ height: 100 }} />
```

All controlled input kinds participate in NatUI's [sequence acknowledgement protocol](/docs/guides/controlled-state).