05 · Forms — dates and values

NumberStepper

stepper_style inset · round · joined × size sm/md/lg · prefix/suffix · locale pt-BR · decimals · min/max · filled · disabled

A number with locale separators (1.234,56) and − and + buttons that add the step.

Clicking +

.heex
<div class="flex flex-wrap items-center gap-2.5"><.number_input id="ns-loop-inset" steppers loop /><.number_input id="ns-loop-round" steppers stepper_style="round" loop /><.number_input id="ns-loop-joined" steppers stepper_style="joined" loop /></div>

stepper_style × size

smmdlginset
12
12
12
round
12
12
12
joined
12
12
12
.heex
<div class="grid grid-cols-[90px_repeat(3,minmax(0,1fr))] items-center gap-x-3 gap-y-2.5"><span></span><span class="text-center font-mono text-xs text-muted">sm</span><span class="text-center font-mono text-xs text-muted">md</span><span class="text-center font-mono text-xs text-muted">lg</span><span class="font-mono text-xs text-muted">inset</span><div class="flex min-w-0 justify-center"><.number_input id="ns-inset-sm" steppers stepper_style="inset" size="sm" value={12} /></div><div class="flex min-w-0 justify-center"><.number_input id="ns-inset-md" steppers stepper_style="inset" size="md" value={12} /></div><div class="flex min-w-0 justify-center"><.number_input id="ns-inset-lg" steppers stepper_style="inset" size="lg" value={12} /></div><span class="font-mono text-xs text-muted">round</span><div class="flex min-w-0 justify-center"><.number_input id="ns-round-sm" steppers stepper_style="round" size="sm" value={12} /></div><div class="flex min-w-0 justify-center"><.number_input id="ns-round-md" steppers stepper_style="round" size="md" value={12} /></div><div class="flex min-w-0 justify-center"><.number_input id="ns-round-lg" steppers stepper_style="round" size="lg" value={12} /></div><span class="font-mono text-xs text-muted">joined</span><div class="flex min-w-0 justify-center"><.number_input id="ns-joined-sm" steppers stepper_style="joined" size="sm" value={12} /></div><div class="flex min-w-0 justify-center"><.number_input id="ns-joined-md" steppers stepper_style="joined" size="md" value={12} /></div><div class="flex min-w-0 justify-center"><.number_input id="ns-joined-lg" steppers stepper_style="joined" size="lg" value={12} /></div></div>

prefix · suffix · decimals · no buttons

Preço R$ 1,284.90
Desconto 12.5 %
Peso 0.750 kg
Quantidade un 3
.heex
<div class="grid grid-cols-4 gap-4"><.number_input id="ns-price" label="Preço" prefix="R$" decimals={2} value={1284.9} align="right" /><.number_input id="ns-disc" label="Desconto" suffix="%" max_decimals={2} value={12.5} align="right" /><.number_input id="ns-weight" label="Peso" suffix="kg" decimals={3} value={0.75} align="right" /><.number_input id="ns-qty" label="Quantidade" prefix="un" steppers value={3} /></div>

filled · disabled · at the limit

8 0
max=10 10
.heex
<div class="flex flex-wrap items-center gap-2.5"><.number_input id="ns-filled" variant="filled" steppers value={8} /><.number_input id="ns-dis" disabled steppers value={0} /><.number_input id="ns-max" label="max=10" max={10} steppers value={10} /></div>

API values that complete the parity

12 variant=outlined
12 shape=rounded
12 shape=pill
1,284.90 align=left
1,284.90 align=right
.heex
<div class="grid grid-cols-5 gap-3.5"><div class="flex flex-col items-start gap-1.5"><.number_input id="ns-v" steppers value={12} variant="outlined" /><span class="font-mono text-[11px] text-muted">variant=outlined</span></div><div class="flex flex-col items-start gap-1.5"><.number_input id="ns-s1" steppers value={12} shape="rounded" /><span class="font-mono text-[11px] text-muted">shape=rounded</span></div><div class="flex flex-col items-start gap-1.5"><.number_input id="ns-s2" steppers value={12} shape="pill" /><span class="font-mono text-[11px] text-muted">shape=pill</span></div><div class="flex flex-col items-start gap-1.5"><.number_input id="ns-a1" value={1284.9} decimals={2} align="left" /><span class="font-mono text-[11px] text-muted">align=left</span></div><div class="flex flex-col items-start gap-1.5"><.number_input id="ns-a2" value={1284.9} decimals={2} align="right" /><span class="font-mono text-[11px] text-muted">align=right</span></div></div>

Usage

<.number_input field={@form[:qty]} steppers min={1} max={99} />
<.number_input field={@form[:price]} decimals={2} prefix="R$" />
<.number_input field={@form[:discount]} suffix="%" max_decimals={1} stepper_style="round" />

Rules

  • inset (default): buttons inside the field; round: two round buttons around the number; joined: buttons attached with a divider.
  • decimals={2} always shows two decimals (money); pt-BR writes 1.234,56.
  • At the limit (min/max) the button is disabled.

API reference

Todos os function components, atributos, valores e slots que este componente cobre.

A numeric field for money and quantities that shows the number the way the person's locale writes it (1.234,56 in pt-BR, 1,234.56 in en) and submits the plain machine value (1234.56).

<.number_input field={@form[:price]} label="Price" prefix="R$" decimals={2} min={0} />
<.number_input field={@form[:quantity]} label="Quantity" steppers min={1} step={1} suffix="un" />
<.number_input name="qty" value={3} steppers stepper_style="round" min={0} />

The control is the design's number box: the number is a span[data-part=number-value] that the LedgerUI.NumberInput hook (priv/static/ledger_ui/hooks/number_input.js) makes editable (contenteditable, role="spinbutton"); a hidden input named like the field carries the machine value and fires a bubbling input event when it changes, so a surrounding phx-change runs. Typing keeps what the person writes; leaving the field clamps to min/max, rounds to decimals/max_decimals and writes it grouped. Arrow up/down (and the steppers) move by step, Page up/down by ten steps. The steppers are disabled at min and max by the hook.

Deviations from the README: align defaults to "center" (the design's value), and the accessible names of the steppers default to the locale's (Diminuir/Aumentar in pt-BR).

<.number_input>

Renders the number input.

Attr Type Default Values / notes
id :string nil
name :string nil
value :any
field {:struct, Phoenix.HTML.FormField} nil
label :string nil
label_class :any nil
help :string nil
errors :list []
disabled :boolean false
locale :string "pt-BR" pt-BR, pt_BR, en
decimal_separator :string nil
thousands_separator :string nil
decimals :integer nil
max_decimals :integer nil
min :any nil
max :any nil
step :any 1
steppers :boolean false
stepper_style :string "inset" inset, round, joined
decrement_label :string nil
increment_label :string nil
prefix :string nil
suffix :string nil
variant :string "outlined" outlined, filled
size :string "md" sm, md, lg
shape :string "rounded" rounded, pill
align :string "center" left, right, center
wrapper_class :any nil
canvas :boolean false The block of the canvas app templates: a div with 14px icons (otherwise a span).
loop :boolean false Demo animation (CSS only): the number counts 1 to 5 and back while the + button is pressed. The text is drawn by a counter, so value is not shown.
class :any nil

Any other HTML/phx attribute goes to the root element.

<.number_stepper>

Same as number_input/1 (same attributes and slots), under the name the design vitrine uses.

Attr Type Default Values / notes
id :string nil
name :string nil
value :any
field {:struct, Phoenix.HTML.FormField} nil
label :string nil
label_class :any nil
help :string nil
errors :list []
disabled :boolean false
locale :string "pt-BR" pt-BR, pt_BR, en
decimal_separator :string nil
thousands_separator :string nil
decimals :integer nil
max_decimals :integer nil
min :any nil
max :any nil
step :any 1
steppers :boolean false
stepper_style :string "inset" inset, round, joined
decrement_label :string nil
increment_label :string nil
prefix :string nil
suffix :string nil
variant :string "outlined" outlined, filled
size :string "md" sm, md, lg
shape :string "rounded" rounded, pill
align :string "center" left, right, center
wrapper_class :any nil
canvas :boolean false The block of the canvas app templates: a div with 14px icons (otherwise a span).
loop :boolean false Demo animation (CSS only): the number counts 1 to 5 and back while the + button is pressed. The text is drawn by a counter, so value is not shown.
class :any nil

Any other HTML/phx attribute goes to the root element.