# `PhiaUi.Components.UnitInput`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/components/inputs/unit_input.ex#L1)

Number input with a semantic unit prefix or suffix.

Provides `unit_input/1` — a number input that displays a unit symbol
(currency, percentage, weight, volume, time, or any custom string) as a
visual decoration inside the field. Also provides `form_unit_input/1` for
changeset-integrated forms.

## When to use

Use `unit_input/1` instead of a bare `<input type="number">` whenever the
unit context is important — prices, percentages, distances, weights, speeds,
durations, ratings, or any dimensioned quantity.

## Presets

The `:unit` attribute accepts shorthand presets:

| Preset | Symbol | Position |
|--------|--------|----------|
| `:currency_usd` | `$` | left |
| `:currency_eur` | `€` | left |
| `:currency_gbp` | `£` | left |
| `:percent` | `%` | right |
| `:kg` | `kg` | right |
| `:lbs` | `lbs` | right |
| `:km` | `km` | right |
| `:mi` | `mi` | right |
| `:m` | `m` | right |
| `:cm` | `cm` | right |
| `:custom` | uses `:symbol` | uses `:symbol_position` |

## Basic usage

    <%!-- Price field --%>
    <.unit_input name="price" value={@price} unit="currency_usd" min="0" step="0.01" />

    <%!-- Percentage --%>
    <.unit_input name="discount" value={@discount} unit="percent" min="0" max="100" />

    <%!-- Custom unit --%>
    <.unit_input name="speed" value={@speed} unit="custom" symbol="km/h" symbol_position="right" />

## Form-integrated

    <.form_unit_input field={@form[:price]} label="Price" unit="currency_usd" step="0.01" />

# `form_unit_input`

Renders a form-integrated unit input with label and error messages.

## Examples

    <.form_unit_input field={@form[:price]} label="Price" unit="currency_usd" step="0.01" />

    <.form_unit_input field={@form[:commission]} label="Commission" unit="percent" max="100" />

## Attributes

* `field` (`Phoenix.HTML.FormField`) (required) - A `Phoenix.HTML.FormField` struct from `@form[:field_name]`.
* `label` (`:string`) - Label text rendered above the input. Defaults to `nil`.
* `description` (`:string`) - Helper text rendered below the label. Defaults to `nil`.
* `unit` (`:string`) - Unit preset. Defaults to `"custom"`.
* `symbol` (`:string`) - Custom symbol string. Defaults to `nil`.
* `symbol_position` (`:string`) - Symbol position. Defaults to `"left"`. Must be one of `"left"`, or `"right"`.
* `min` (`:any`) - Minimum value. Defaults to `nil`.
* `max` (`:any`) - Maximum value. Defaults to `nil`.
* `step` (`:any`) - Step increment. Defaults to `nil`.
* `placeholder` (`:string`) - Placeholder text. Defaults to `nil`.
* `class` (`:string`) - Additional CSS classes for the wrapper. Defaults to `nil`.
* Global attributes are accepted. HTML attributes forwarded to `unit_input/1`. Supports all globals plus: `["phx-change", "phx-debounce", "disabled", "required", "readonly"]`.

# `unit_input`

Renders a number input with a unit symbol prefix or suffix.

## Examples

    <.unit_input name="price" value={@price} unit="currency_usd" step="0.01" />

    <.unit_input name="weight" value={@weight} unit="kg" min="0" max="500" />

    <.unit_input name="rate" value={@rate} unit="percent" min="0" max="100" />

    <.unit_input name="temp" value={@temp} unit="custom" symbol="°C" symbol_position="right" />

## Attributes

* `id` (`:string`) - HTML id for the `<input>`. Auto-generated if nil. Defaults to `nil`.
* `name` (`:string`) - HTML name attribute. Defaults to `nil`.
* `value` (`:any`) - Current numeric value. Defaults to `nil`.
* `unit` (`:string`) - Unit preset or `"custom"`. See module docs for available presets. Defaults to `"custom"`.
* `symbol` (`:string`) - Symbol string used when `:unit` is `"custom"`. Defaults to `nil`.
* `symbol_position` (`:string`) - Where to place the symbol when `:unit` is `"custom"`. Defaults to `"left"`. Must be one of `"left"`, or `"right"`.
* `min` (`:any`) - Minimum value (`min` HTML attribute). Defaults to `nil`.
* `max` (`:any`) - Maximum value (`max` HTML attribute). Defaults to `nil`.
* `step` (`:any`) - Step increment (`step` HTML attribute). Defaults to `nil`.
* `placeholder` (`:string`) - Placeholder text. Defaults to `nil`.
* `disabled` (`:boolean`) - Disables the input. Defaults to `false`.
* `readonly` (`:boolean`) - Makes the input read-only. Defaults to `false`.
* `class` (`:string`) - Additional CSS classes merged into the outer wrapper. Defaults to `nil`.
* Global attributes are accepted. HTML attributes forwarded to the `<input>` element. Supports all globals plus: `["phx-change", "phx-debounce", "required", "autocomplete", "phx-keydown"]`.

---

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