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

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

Locales are displayed with their localized display name. A special `:identity` mode renders each locale's name in its own language. The list of locales, sort order, and display format are all configurable.

# `locale`

```elixir
@type locale() :: %{
  locale: String.t(),
  display_name: String.t(),
  language_tag: Localize.LanguageTag.t()
}
```

# `mapper`

```elixir
@type mapper() :: (locale() -&gt; String.t())
```

# `select_options`

```elixir
@type select_options() :: [
  {:locales, [atom() | binary(), ...]}
  | {:locale, Localize.locale() | Localize.LanguageTag.t() | :identity}
  | {:collator, function()}
  | {:mapper, function()}
  | {:selected, atom() | binary()}
  | {atom(), any()}
]
```

# `locale_options`

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

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

### Returns

* A list of `{display_name, locale_string}` 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 locale 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

* `:locales` defines the list of locales to be displayed in the select tag. The default is `Localize.all_locale_ids/0` with meta locales excluded.

* `:locale` defines the locale used to localise the display names. The default is the locale returned by `Localize.get_locale/0`. If set to `:identity` then each locale in `:locales` will be rendered in its own locale.

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

* `:mapper` is a function that creates the text to be displayed in the select tag for each locale. It receives a map with `:display_name`, `:locale` and `:language_tag` keys. The default mapper is `&{&1.display_name, &1.locale}`.

* `:selected` identifies the locale 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.Locale.select(:my_form, :locale_list, selected: "en")

---

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