# `Money.Input.Components`
[🔗](https://github.com/ex-money/money_input/blob/v0.3.3/lib/money/input/components.ex#L3)

HEEx components for locale-aware money input.

Two components ship from this module:

* `money_input/1` — money input with a fixed currency or an
  embedded `currency_picker/1`.
* `currency_picker/1` — first-class searchable currency picker
  (flag glyphs, recents in `localStorage`, mobile sheet
  variant, keyboard nav).

Both render their HTML baseline server-side and degrade
gracefully when JS is disabled. With the JS hook loaded
(`priv/static/money_input.js`), they upgrade to live
formatting and full picker behaviour.

For a plain *number* input (no currency), use
[`Localize.Inputs.Components.number_input/1`](https://hexdocs.pm/localize_inputs)
from the sibling `localize_inputs` package.

## Setup

Add the JS hooks in your `assets/js/app.js`:

    import { MoneyInput, CurrencyPicker } from "ex_money_input"
    let Hooks = {}
    Hooks.MoneyInput = MoneyInput
    Hooks.CurrencyPicker = CurrencyPicker

And install the AutoNumeric peer dep:

    npm install autonumeric

See `Money.Input` for a full feature overview.

## Tolerance of invalid input

These components sit on the render path and never raise on
bad input — the page always renders. Specifically:

* **Unknown `:locale`** — each component validates `:locale`
  once with `Localize.validate_locale/1` and works from the
  resulting `t:Localize.LanguageTag.t/0`. An invalid locale
  renders without locale data: no `data-locale` or separator
  attributes, a blank amount, and the currencies' English
  names in the picker.

* **Unknown `:default_currency`** (e.g. `:ZZZ`, `:""`,
  `nil`) — falls back to the locale's natural currency.
  Empty strings and the `:""` atom in form-submitted
  `currency` values are explicitly blacklisted by
  `normalize_currency_code/1` so they never reach a
  downstream `Money.Currency` lookup.

* **Blank or unparseable `value`** — the visible input
  renders empty; the hidden currency carrier stays at
  the default. `Money.Input.Cast.cast/2` returns
  `{:ok, nil}` for blanks and `{:error, _}` for garbage,
  never raises.

* **JS hook absent** — both components degrade to plain
  HTML form inputs. Live formatting and the picker
  overlay are off; the form still submits a valid
  `%{"amount", "currency"}` map for `Money.Ecto.Composite.Type`.

# `currency_picker`

First-class searchable currency picker.

Renders as a trigger button (flag + ISO code). Clicking opens
an overlay with a search input, recent selections (persisted
in `localStorage`), pinned preferred currencies, and the full
sorted currency list. On mobile, the overlay becomes a
full-screen sheet.

### Examples

    <.currency_picker
      form={@form}
      field={:currency}
      current={:USD}
      preferred={[:USD, :EUR, :GBP, :JPY]}
    />

## Attributes

* `form` (`Phoenix.HTML.Form`) - Defaults to `nil`.
* `field` (`:atom`) - Defaults to `nil`.
* `name` (`:string`) - Explicit hidden-input name. Overrides form+field. Used by `money_input/1` to inject a nested name like `price[currency]`. Defaults to `nil`.
* `input_id` (`:string`) - Explicit id for the hidden value input. Defaults to `nil`.
* `current` (`:atom`) (required)
* `allowed` (`:list`) - Defaults to `nil`.
* `preferred` (`:list`) - Defaults to `[]`.
* `recents_limit` (`:integer`) - Defaults to `5`.
* `locale` (`:any`) - A locale string, atom or `Localize.LanguageTag`. Defaults to the current locale (`Localize.get_locale/0`). Defaults to `nil`.
* `variant` (`:atom`) - Defaults to `:auto`. Must be one of `:auto`, `:dropdown`, or `:sheet`.
* `id` (`:string`) - Defaults to `nil`.
* `class` (`:string`) - Defaults to `nil`.
* `button_class` (`:string`) - Defaults to `nil`.
* `overlay_class` (`:string`) - Defaults to `nil`.
* `row_class` (`:string`) - Defaults to `nil`.

# `money_input`

Locale-aware money input.

Returns `t:Money.t/0` on form submission. Renders the currency
symbol as an adornment outside the input — the user only
types digits and a decimal separator.

With `currency_picker={true}`, embeds the bundled
`currency_picker/1` in the symbol-adornment position so the
user can switch currencies. Currency-aware precision: USD
accepts 2 decimals, JPY 0, BHD 3.

### Attributes

* `:default_currency` — the currency used when the form value
  doesn't carry one and the user hasn't (yet) picked one. With
  the picker off this is the only currency the field accepts.
  With the picker on it pre-selects the trigger and acts as
  the fallback when the form value is blank.

### Examples

    <.money_input form={@form} field={:price} default_currency={:USD} />

    <.money_input
      form={@form}
      field={:price}
      default_currency={:USD}
      currency_picker={true}
      preferred_currencies={[:USD, :EUR, :GBP]}
    />

## Attributes

* `form` (`Phoenix.HTML.Form`) (required)
* `field` (`:atom`) (required)
* `value` (`:any`) - Defaults to `nil`.
* `locale` (`:any`) - A locale string, atom or `Localize.LanguageTag`. Defaults to the current locale (`Localize.get_locale/0`). Defaults to `nil`.
* `default_currency` (`:atom`) - The currency used when the form value doesn't carry one. Pre-selects the picker. Defaults to `nil`.
* `currency_field` (`:atom`) - Defaults to `nil`.
* `min` (`:any`) - Defaults to `nil`.
* `max` (`:any`) - Defaults to `nil`.
* `align` (`:atom`) - Defaults to `:right`. Must be one of `:left`, `:right`, or `:center`.
* `placeholder` (`:string`) - Defaults to `nil`.
* `symbol_position` (`:atom`) - Defaults to `:auto`. Must be one of `:auto`, `:prefix`, or `:suffix`.
* `symbol_kind` (`:atom`) - Defaults to `:symbol`. Must be one of `:symbol`, `:iso`, `:narrow`, or `:none`.
* `js` (`:boolean`) - Defaults to `true`.
* `class` (`:string`) - Defaults to `nil`.
* `input_class` (`:string`) - Defaults to `nil`.
* `symbol_class` (`:string`) - Defaults to `nil`.
* `currency_picker` (`:boolean`) - Defaults to `false`.
* `allowed_currencies` (`:list`) - Defaults to `nil`.
* `preferred_currencies` (`:list`) - Defaults to `[]`.
* Global attributes are accepted. Supports all globals plus: `["disabled", "readonly", "required", "autofocus"]`.

---

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