Localize.Inputs.Number.Components (Localize.Inputs.Number v0.1.1)

HEEx components for locale-aware form input.

Today: number_input/1. More inputs (percentage, ratio, dimension, …) will land here over time under the same namespace.

Setup

Add the JS hook in your assets/js/app.js:

import Hooks from "localize_inputs"
let liveSocket = new LiveSocket("/live", Socket, {
  hooks: { NumberInput: Hooks.NumberInput }
})

Install AutoNumeric as a peer dep:

npm install autonumeric

Tolerance of invalid input

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

Unknown :locale — falls back to :en locale data; if :en itself is unavailable (broken Localize install) falls back to an empty %Localize.Inputs.Number.Symbols{} so attribute reads still resolve to safe defaults.
Unknown :category on unit_input/1 — falls back to an empty %Localize.Inputs.Number.Unit{}. The picker renders no rows rather than 500ing the page.
Blank or non-numeric value — formatted as "" in the visible input; the hidden ISO carrier stays empty. The submit-side parser (Localize.Inputs.Number.Parser.parse_number/2) returns {:ok, nil} for blanks and {:error, _} for garbage, never raises.
Malformed :min / :max / :decimals bounds — Localize.Inputs.Number.Validator.validate_number/2 uses Decimal.parse/1 with a Decimal.new(0) fallback, so a typo in a bound silently passes the bound check rather than crashing the validation pipeline. Returns {:error, %ValidationError{}} for real out-of-range values.

Summary

Functions

number_input(assigns)

Locale-aware plain-number input.

unit_input(assigns)

Locale-aware number + unit-of-measure input.

unit_picker(assigns)

Standalone locale-aware unit picker.

Functions

number_input(assigns)

Locale-aware plain-number input.

Renders an <input type="text" inputmode="decimal"> wrapped in a <div> that carries data- attributes the JS hook reads (locale, separators, minus sign, min/max, decimals). With AutoNumeric loaded the input live-formats as the user types; without it, the server-side parser (Localize.Inputs.Number.Parser.parse_number/2) accepts whatever the user typed on submit.

The form value submits in the user's locale-formatted shape — exactly what AutoNumeric was displaying. Parse it on the server with Localize.Inputs.Number.Parser.parse_number/2 (or Localize.Inputs.Number.Changeset.validate_number/3 for an Ecto-backed flow). One wire shape regardless of whether the JS hook is loaded — no canonical-vs-locale ambiguity.

Arguments

assigns — see the per-attribute documentation below.

Attributes

:form — the Phoenix.HTML.Form the field belongs to.
:field — the form field as an atom.
:locale — display locale. Defaults to Localize.get_locale/0.
:integer — when true, accept integers only and emit inputmode="numeric".
:min, :max — value bounds.
:decimals — maximum fractional digits.
:align — :left (default), :right, or :center.
:placeholder — placeholder text.
:js — set to false to skip the phx-hook attribute.
:class, :input_class — extra classes for the wrapper and the input.

Returns

A Phoenix.LiveView.Rendered struct containing the input markup.

Examples

<.number_input form={@form} field={:quantity} integer={true} min={1} max={999} />
<.number_input form={@form} field={:rating} min={0} max={5} decimals={1} />

Attributes

form (Phoenix.HTML.Form) (required)
field (:atom) (required)
value (:any) - Defaults to nil.
locale (:string) - Defaults to nil.
integer (:boolean) - Defaults to false.
min (:any) - Defaults to nil.
max (:any) - Defaults to nil.
decimals (:integer) - Defaults to nil.
align (:atom) - Defaults to :left. Must be one of :left, :right, or :center.
placeholder (:string) - Defaults to nil.
js (:boolean) - Defaults to true.
class (:string) - Defaults to nil.
input_class (:string) - Defaults to nil.
Global attributes are accepted. Supports all globals plus: ["disabled", "readonly", "required", "autofocus"].

unit_input(assigns)

Locale-aware number + unit-of-measure input.

Renders a number input paired with a searchable unit_picker/1 for a given measurement category ("length", "volume", "mass", …). The picker is grouped into Preferred (units in the locale's measurement system — metric, US, or UK) and All units (every known unit in the category). Unit display names are localized via Localize.Unit.display_name/2.

Submits as a nested map:

params[field] = %{"amount" => "1.5", "unit" => "meter"}

Parse on the server with the locale you already have.

Attributes

:form — the Phoenix.HTML.Form the field belongs to.
:field — the form field as an atom. The amount and unit sub-fields submit under params[field][amount] and params[field][unit].
:category — the unit category as a string (e.g. "length"). Required. See Localize.Inputs.Number.Unit.known_categories/0.
:default_unit — the unit selected by default. If nil, the first preferred unit for the locale is selected.
:locale — display locale. Defaults to Localize.get_locale/0.
:integer, :min, :max, :decimals, :align, :placeholder, :js, :class, :input_class — passed through to the underlying number_input/1.
:include_prefixed — when true, the All-units section includes SI-prefixed variants (e.g. decimeter). The default is false to keep the list manageable.

Examples

<.unit_input form={@form} field={:height} category="length" />

<.unit_input
  form={@form}
  field={:weight}
  category="mass"
  default_unit="kilogram"
  min={0}
/>

Attributes

form (Phoenix.HTML.Form) (required)
field (:atom) (required)
category (:string) (required)
default_unit (:string) - Defaults to nil.
locale (:string) - Defaults to nil.
value (:any) - Defaults to nil.
integer (:boolean) - Defaults to false.
min (:any) - Defaults to nil.
max (:any) - Defaults to nil.
decimals (:integer) - Defaults to nil.
align (:atom) - Defaults to :left. Must be one of :left, :right, or :center.
placeholder (:string) - Defaults to nil.
include_prefixed (:boolean) - Defaults to false.
js (:boolean) - Defaults to true.
class (:string) - Defaults to nil.
input_class (:string) - Defaults to nil.
picker_class (:string) - Defaults to nil.
Global attributes are accepted. Supports all globals plus: ["disabled", "readonly", "required", "autofocus"].

unit_picker(assigns)

Standalone locale-aware unit picker.

Searchable picker grouped into a Preferred section (units in the locale's measurement system) and an All units section (every known unit in the category). Selecting a row updates a hidden input that the picker serialises on form submission and emits a localize-inputs:unit-change CustomEvent so any enclosing unit_input/1 can react.

Attributes

:current — the currently-selected unit name (string). Required.
:category — the unit category. Required.
:locale — display locale. Defaults to Localize.get_locale/0.
:form + :field — when given, the hidden value input is named Phoenix.HTML.Form.input_name(form, field).
:name — explicit hidden-input name. Overrides :form/:field. Used by unit_input/1 to inject a nested name like height[unit].
:input_id — explicit id for the hidden value input.
:include_prefixed — when true, the All-units section includes SI-prefixed variants.
:variant — :auto (default), :dropdown, or :sheet.
:id, :class, :button_class, :overlay_class, :row_class — customisation hooks.

Attributes

form (Phoenix.HTML.Form) - Defaults to nil.
field (:atom) - Defaults to nil.
name (:string) - Explicit hidden-input name. Overrides form+field. Used by unit_input/1 to inject a nested name like height[unit]. Defaults to nil.
input_id (:string) - Explicit id for the hidden value input. Defaults to nil.
current (:string) (required)
category (:string) (required)
locale (:any) - Defaults to nil.
include_prefixed (:boolean) - Defaults to false.
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.