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

Copy Markdown View Source

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 hooks in your assets/js/app.js:

import AutoNumeric from "autonumeric"
import Hooks from "localize_number_inputs"

Hooks.configure({ AutoNumeric })

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

"localize_number_inputs" resolves because Phoenix's generated esbuild config puts deps on NODE_PATH, as it does for "phoenix_html". If your build doesn't, import "../../deps/localize_number_inputs/priv/static/localize_number_inputs.js" instead.

Install AutoNumeric as a peer dep:

npm install autonumeric

Digits

AutoNumeric writes and accepts Latin digits (0–9) only. With it loaded, a field in a locale that has digits of its own (fa, ckb, bn, mr, my and others) switches to Latin digits when the hook starts, and digits typed or pasted in the locale's own script are ignored. The submitted text keeps the locale's separators and minus sign, and Localize.Inputs.Number.Parser.parse_number/2 reads it back.

Without AutoNumeric the field is a plain input. The server renders the locale's digits, and the parser accepts the locale's digits and Latin digits alike. If AutoNumeric rejects a locale's symbols, the hook falls back to that plain input.

Grouping

The hook groups digits as the locale's standard number format does: in threes (1,234,567), in the Indian lakh and crore pattern (12,34,567 in hi, bn, en-IN and others) or in twos (tok). AutoNumeric always groups, so in locales that leave a four-digit number ungrouped (es, pl and others) it shows 1.234 where the server renders 1234. The parser reads both.

Tolerance of invalid input

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

  • Unknown :locale — renders as :en, the value as well as the locale data. If :en itself is unavailable (broken Localize install) it 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

Locale-aware plain-number input.

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

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). The input carries the value as a plain decimal string in data-amount ("1234.56"), which the hook starts AutoNumeric from and resyncs to after each LiveView update. 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. AutoNumeric shows and accepts Latin digits only, in every locale; see "Digits" in the module documentation.

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, as a string, an atom or a Localize.LanguageTag.t/0. Defaults to Localize.get_locale/0. It is validated once per render; an invalid locale renders with :en.

  • :integer — when true, accept integers only and emit inputmode="numeric".

  • :min, :max — value bounds.

  • :decimals — maximum fractional digits the user can type. A value with more is shown with all its digits, never rounded, for Localize.Inputs.Number.Validator to report.

  • :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

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 (: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.
  • 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, as a string, an atom or a Localize.LanguageTag.t/0. Defaults to Localize.get_locale/0. It is validated once per render; an invalid locale renders with :en.

  • :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 (:any) - 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, as a string, an atom or a Localize.LanguageTag.t/0. Defaults to Localize.get_locale/0. It is validated once per render; an invalid locale renders with :en.

  • :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.