# `Localize.HTML.Subdivision`
[🔗](https://github.com/elixir-localize/localize_web/blob/main/lib/localize/html/subdivision.ex#L1)

Generates HTML `<select>` tags and option lists for the subdivisions of a territory — US states, Canadian provinces, French departments and so on.

Subdivision codes in CLDR carry their territory: California is `:usca`, not `:ca`. The territory is stripped from the option value, so a form receives `"ca"` and stores the subdivision as it is written in an address. The `:full_codes` option keeps the CLDR form where the value must remain globally unique.

# `select_options`

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

# `subdivision`

```elixir
@type subdivision() :: %{
  subdivision_code: String.t(),
  full_code: atom(),
  name: String.t()
}
```

Subdivision type passed to a collator for ordering in the select box.

# `select`

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

Returns a `<select>` tag of the subdivisions of a territory.

### Arguments

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

* `field` is the field name in `form`.

* `options` is a keyword list of options.

### Options

* `:territory` is the territory whose subdivisions are listed, for example `:US`. Required.

* `:locale` is any locale returned by `Localize.all_locale_ids/0`. The default is `Localize.get_locale/0`.

* `:full_codes` keeps the CLDR subdivision code (`:usca`) as the option value rather than stripping the territory (`"ca"`). The default is `false`.

* `:selected` is the subdivision to mark as selected. Accepts either form of the code.

* `:collator` orders the subdivisions. The default sorts by localized name using `Localize.Collation.sort/2`, so the order is correct for the locale.

* `:mapper` builds each option from a `t:subdivision/0`. The default is `&{&1.name, &1.subdivision_code}`.

Remaining options are passed to `PhoenixHTMLHelpers.Form.select/4`.

### Returns

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

* `{:error, exception}` if the territory or locale is invalid.

### Examples

    Localize.HTML.Subdivision.select(:address, :state, territory: :US)

    Localize.HTML.Subdivision.select(:address, :state, territory: :US, locale: :fr)

# `subdivision_options`

```elixir
@spec subdivision_options(select_options()) :: [tuple()] | {:error, term()}
```

Returns the subdivisions of a territory as a list of `{name, code}` tuples.

Takes the same options as `select/3`.

### Returns

* A list of `{name, code}` tuples, or

* `{:error, exception}` if the territory or locale is invalid.

### Examples

    iex> {name, code} = Localize.HTML.Subdivision.subdivision_options(territory: :US) |> hd()
    iex> {name, code}
    {"Alabama", "al"}

---

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