# `Toddy.Iced.Widget.TextInput`
[🔗](https://github.com/toddy-ui/toddy-elixir/blob/v0.3.0/lib/toddy/iced/widget/text_input.ex#L1)

Text input field -- single-line editable text.

Emits `%Widget{type: :input, id: id, value: value}` on every keystroke.

## Props

- `value` (string) -- current text content. Required for controlled input.
- `placeholder` (string) -- placeholder text shown when value is empty.
- `padding` (number | map) -- internal padding. See `Toddy.Iced.Padding`.
- `width` (length) -- input width. Default: fill. See `Toddy.Iced.Length`.
- `size` (number) -- font size in pixels.
- `font` (string | map) -- font specification. See `Toddy.Iced.Font`.
- `line_height` (number | map) -- line height. Number is a relative multiplier;
  map with `%{relative: n}` or `%{absolute: n}` for explicit control.
- `align_x` (atom) -- text horizontal alignment: `:left`, `:center`, `:right`.
  See `Toddy.Iced.Alignment`.
- `on_submit` (any) -- when present (any truthy value), enables submit on Enter.
  Emits `%Widget{type: :submit, id: id, value: value}`.
- `id` (string) -- widget ID for programmatic focus via `Toddy.Command.focus/1`.
- `style` (atom) -- named style. Currently only `:default`.
- `icon` (map) -- display an icon inside the input field. Map with keys:
  - `code_point` (string) -- single character to render as the icon. Required.
  - `size` (number) -- icon font size in pixels. Optional.
  - `spacing` (number) -- pixels between icon and text. Default: 4.0.
  - `side` (string) -- `"left"` or `"right"`. Default: `"left"`.
  - `font` (string | map) -- icon font. Default: system default.
- `on_paste` (boolean) -- when true, emits `%Widget{type: :paste, id: id, value: text}` when user
  pastes text. Default: false.
- `secure` (boolean) -- mask input as password dots. Default: false.
- `ime_purpose` (string) -- IME input purpose hint: `"normal"`, `"secure"`, `"terminal"`.
  Overrides the default derived from `secure`. Default: nil (auto from `secure`).
- `placeholder_color` (color) -- placeholder text color. See `Toddy.Iced.Color`.
- `selection_color` (color) -- text selection highlight color. See `Toddy.Iced.Color`.
- `a11y` (map) -- accessibility overrides. See `Toddy.Iced.A11y`.

## Events

- `%Widget{type: :input, id: id, value: value}` -- emitted on every text change.
- `%Widget{type: :submit, id: id, value: value}` -- emitted on Enter (requires `on_submit` prop).
- `%Widget{type: :paste, id: id, value: text}` -- emitted on paste (requires `on_paste` prop).

# `option`

```elixir
@type option() ::
  {:placeholder, String.t()}
  | {:padding, Toddy.Iced.Padding.t()}
  | {:width, Toddy.Iced.Length.t()}
  | {:size, number()}
  | {:font, Toddy.Iced.Font.t()}
  | {:line_height, number() | map()}
  | {:align_x, Toddy.Iced.Alignment.t()}
  | {:icon, map()}
  | {:on_submit, boolean()}
  | {:on_paste, boolean()}
  | {:secure, boolean()}
  | {:ime_purpose, String.t()}
  | {:style, style()}
  | {:placeholder_color, Toddy.Iced.Color.input()}
  | {:selection_color, Toddy.Iced.Color.input()}
  | {:a11y, Toddy.Iced.A11y.t()}
```

# `style`

```elixir
@type style() :: :default | Toddy.Iced.StyleMap.t()
```

# `t`

```elixir
@type t() :: %Toddy.Iced.Widget.TextInput{
  a11y: Toddy.Iced.A11y.t() | nil,
  align_x: Toddy.Iced.Alignment.t() | nil,
  font: Toddy.Iced.Font.t() | nil,
  icon: map() | nil,
  id: String.t(),
  ime_purpose: String.t() | nil,
  line_height: number() | map() | nil,
  on_paste: boolean() | nil,
  on_submit: boolean() | nil,
  padding: Toddy.Iced.Padding.t() | nil,
  placeholder: String.t() | nil,
  placeholder_color: Toddy.Iced.Color.t() | nil,
  secure: boolean() | nil,
  selection_color: Toddy.Iced.Color.t() | nil,
  size: number() | nil,
  style: style() | nil,
  value: String.t(),
  width: Toddy.Iced.Length.t() | nil
}
```

# `a11y`

```elixir
@spec a11y(text_input :: t(), a11y :: Toddy.Iced.A11y.t()) :: t()
```

Sets accessibility annotations.

# `align_x`

```elixir
@spec align_x(text_input :: t(), align_x :: Toddy.Iced.Alignment.t()) :: t()
```

Sets the horizontal text alignment.

# `build`

```elixir
@spec build(text_input :: t()) :: Toddy.Iced.ui_node()
```

Converts this text input struct to a `ui_node()` map via the `Toddy.Iced.Widget` protocol.

# `font`

```elixir
@spec font(text_input :: t(), font :: Toddy.Iced.Font.t()) :: t()
```

Sets the font.

# `icon`

```elixir
@spec icon(text_input :: t(), icon :: map()) :: t()
```

Sets the icon displayed inside the input field.

# `ime_purpose`

```elixir
@spec ime_purpose(text_input :: t(), ime_purpose :: String.t()) :: t()
```

Sets the IME input purpose hint. Overrides the default derived from `secure`.

# `line_height`

```elixir
@spec line_height(text_input :: t(), line_height :: number() | map()) :: t()
```

Sets the line height.

# `new`

```elixir
@spec new(id :: String.t(), value :: String.t(), opts :: [option()]) :: t()
```

Creates a new text input struct with the given value and optional keyword opts.

# `on_paste`

```elixir
@spec on_paste(text_input :: t(), on_paste :: boolean()) :: t()
```

Enables or disables paste event emission.

# `on_submit`

```elixir
@spec on_submit(text_input :: t(), on_submit :: boolean()) :: t()
```

Enables or disables submit on Enter.

# `padding`

```elixir
@spec padding(text_input :: t(), padding :: Toddy.Iced.Padding.t()) :: t()
```

Sets the internal padding.

# `placeholder`

```elixir
@spec placeholder(text_input :: t(), placeholder :: String.t()) :: t()
```

Sets the placeholder text.

# `placeholder_color`

```elixir
@spec placeholder_color(text_input :: t(), color :: Toddy.Iced.Color.input()) :: t()
```

Sets the placeholder text color. Accepts any form `Color.cast/1` supports.

# `secure`

```elixir
@spec secure(text_input :: t(), secure :: boolean()) :: t()
```

Sets whether input is masked as a password.

# `selection_color`

```elixir
@spec selection_color(text_input :: t(), color :: Toddy.Iced.Color.input()) :: t()
```

Sets the text selection highlight color. Accepts any form `Color.cast/1` supports.

# `size`

```elixir
@spec size(text_input :: t(), size :: number()) :: t()
```

Sets the font size in pixels.

# `style`

```elixir
@spec style(text_input :: t(), style :: style()) :: t()
```

Sets the input style.

# `width`

```elixir
@spec width(text_input :: t(), width :: Toddy.Iced.Length.t()) :: t()
```

Sets the input width.

# `with_options`

```elixir
@spec with_options(text_input :: t(), opts :: [option()]) :: t()
```

Applies keyword options to an existing text input struct.

---

*Consult [api-reference.md](api-reference.md) for complete listing*