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

Generates HTML `<select>` tags and option lists for localized unit-of-measure display.

Units are displayed with their localized display name. The list of units, display style (long, short, narrow), sort order, and display format are all configurable.

# `select_options`

```elixir
@type select_options() :: [
  units: [atom() | binary(), ...],
  locale: Localize.locale() | Localize.LanguageTag.t(),
  collator: function(),
  mapper: (tuple() -&gt; String.t()),
  selected: atom() | binary(),
  style: :long | :short | :narrow
]
```

# `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 unit list that can be used with a `t:Phoenix.HTML.Form.t/0`.

### 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

* `:units` is a list of units to be displayed in the select.

* `:style` is the style of unit name to be displayed. The options are `:long`, `:short` and `:narrow`. The default is `:long`.

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

* `:collator` is a function used to sort the units. The default collator sorts by display name.

* `:mapper` is a function that creates the text to be displayed in the select tag for each unit. It receives a tuple `{display_name, unit_code}`. The default is the identity function.

* `:selected` identifies the unit 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.Unit.select(:my_form, :unit, selected: :foot)

# `unit_options`

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

Generates a list of options for a unit 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.Unit.select/3` for options.

### Returns

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

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

---

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