# `Localize.HTML.Currency`
[🔗](https://github.com/kipcole9/localize_web/blob/main/lib/localize/html/currency.ex#L1)

Generates HTML `<select>` tags and option lists for localized currency display.

Currencies are displayed with their currency code and localized name. The list of currencies, sort order, and display format are all configurable.

# `select_options`

```elixir
@type select_options() :: [
  currencies: [atom() | binary(), ...],
  locale: Localize.locale() | Localize.LanguageTag.t(),
  collator: function(),
  mapper: (Localize.Currency.t() -&gt; String.t()),
  selected: atom() | binary()
]
```

# `currency_options`

```elixir
@spec currency_options(select_options()) :: [tuple()] | {:error, {module(), binary()}}
```

Generates a list of options for a currency list that can be used with `Phoenix.HTML.Form.options_for_select/2` or to create a `<datalist>`.

### Arguments

* `options` is a `t:Keyword.t/0` list of options.

### Options

See `Localize.HTML.Currency.select/3` for options.

### Returns

* A list of `{display_name, currency_code}` tuples, or

* `{:error, {module(), binary()}}` if validation fails.

# `select`

```elixir
@spec select(
  form :: Phoenix.HTML.Form.t(),
  field :: Phoenix.HTML.Form.field(),
  select_options()
) :: Phoenix.HTML.safe() | {:error, {module(), binary()}}
```

Generates an HTML select tag for a currency list that can be used with a `Phoenix.HTML.Form.t`.

### Arguments

* `form` is a `t:Phoenix.HTML.Form.t/0` form.

* `field` is a `t:Phoenix.HTML.Form.field/0` field.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:currencies` defines the list of currencies to be displayed in the select tag. The default is `Localize.Currency.known_currency_codes/0`.

* `:locale` defines the locale to be used to localise the description of the currencies. The default is the locale returned by `Localize.get_locale/0`.

* `:collator` is a function used to sort the currencies in the selection list. The default collator sorts by name.

* `:mapper` is a function that creates the text to be displayed in the select tag for each currency. The default function is `&({&1.code <> " - " <> &1.name, &1.code})`.

* `:selected` identifies the currency that is to be selected by default in the select tag. The default is `nil`.

* `:prompt` is a prompt displayed at the top of the select box.

### Returns

* A `t:Phoenix.HTML.safe/0` select tag, or

* `{:error, {module(), binary()}}` if validation fails.

### Examples

    iex> Localize.HTML.Currency.select(:my_form, :currency, selected: :USD)

---

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