Skip to content

NumberInput

Numeric input with increment/decrement buttons, min/max clamping, step control, and keyboard arrow support. Hold-to-repeat on buttons for fast value changes.

import { NumberInput } from "phoundry-ui";

Basic

Loading interactive example…

View source
basic.svelte
<script lang="ts">
import { NumberInput } from "phoundry-ui";
let basic = $state(42);
</script>
<div class="flex items-center gap-4">
<NumberInput
value={basic}
onchange={(v: number) => {
basic = v;
}}
/>
<span class="text-xs text-txt-tertiary">Value: {basic}</span>
</div>

With Min / Max

Loading interactive example…

View source
with-min-max.svelte
<script lang="ts">
import { NumberInput } from "phoundry-ui";
let bounded = $state(5);
</script>
<div class="flex items-center gap-4">
<NumberInput
value={bounded}
onchange={(v: number) => {
bounded = v;
}}
min={0}
max={10}
/>
<span class="text-xs text-txt-tertiary">Clamped 0–10: {bounded}</span>
</div>

Custom Step

Loading interactive example…

View source
custom-step.svelte
<script lang="ts">
import { NumberInput } from "phoundry-ui";
let stepped = $state(0);
</script>
<div class="flex items-center gap-4">
<NumberInput
value={stepped}
onchange={(v: number) => {
stepped = v;
}}
step={0.25}
min={0}
width="7rem"
/>
<span class="text-xs text-txt-tertiary">Step 0.25: {stepped}</span>
</div>

Sizes

Loading interactive example…

View source
sizes.svelte
<script lang="ts">
import { NumberInput } from "phoundry-ui";
let sizeSm = $state(10);
let sizeMd = $state(10);
let sizeLg = $state(10);
</script>
<div class="flex items-center gap-4">
<div class="flex flex-col items-start gap-1">
<span class="text-[10px] text-txt-tertiary">sm</span>
<NumberInput
value={sizeSm}
onchange={(v: number) => {
sizeSm = v;
}}
size="sm"
/>
</div>
<div class="flex flex-col items-start gap-1">
<span class="text-[10px] text-txt-tertiary">md</span>
<NumberInput
value={sizeMd}
onchange={(v: number) => {
sizeMd = v;
}}
size="md"
/>
</div>
<div class="flex flex-col items-start gap-1">
<span class="text-[10px] text-txt-tertiary">lg</span>
<NumberInput
value={sizeLg}
onchange={(v: number) => (sizeLg = v)}
size="lg"
/>
</div>
</div>

Variants

Loading interactive example…

View source
variants.svelte
<script lang="ts">
import { NumberInput } from "phoundry-ui";
import type { ComponentProps } from "svelte";
type TextFieldVariant = NonNullable<
ComponentProps<typeof NumberInput>["variant"]
>;
let variantValue = $state(10);
const variants: TextFieldVariant[] = [
"outline",
"fill",
"ghost",
"trueGhost",
];
</script>
<div class="flex flex-wrap items-center gap-4">
{#each variants as variant}
<div class="flex flex-col items-start gap-1">
<span class="text-[10px] text-txt-tertiary">{variant}</span>
<NumberInput
value={variantValue}
onchange={(v: number) => (variantValue = v)}
{variant}
/>
</div>
{/each}
</div>

Disabled

Loading interactive example…

View source
disabled.svelte
<script lang="ts">
import { NumberInput } from "phoundry-ui";
let disabledDemo = $state(3);
</script>
<p class="mb-2 text-xs text-txt-secondary">
Steppers are inert and the field does not accept edits.
</p>
<NumberInput
value={disabledDemo}
onchange={(v: number) => (disabledDemo = v)}
disabled
/>

Button Layout

Loading interactive example…

View source
button-layout.svelte
<script lang="ts">
import { NumberInput } from "phoundry-ui";
let basic = $state(42);
</script>
<div class="flex items-center gap-4">
<div class="flex flex-col items-start gap-1">
<span class="text-[10px] text-txt-tertiary">vertical (default)</span>
<NumberInput
value={basic}
onchange={(v: number) => {
basic = v;
}}
/>
</div>
<div class="flex flex-col items-start gap-1">
<span class="text-[10px] text-txt-tertiary">horizontal</span>
<NumberInput
value={basic}
onchange={(v: number) => {
basic = v;
}}
buttonLayout="horizontal"
/>
</div>
</div>

API

From phoundry-ui@0.4.21

NameTypeDefaultDescription
valuerequirednumber—Current numeric value
onchangerequired(value: number) => void—Called when value changes
minnumber—Minimum allowed value
maxnumber—Maximum allowed value
stepnumber1Increment / decrement step
size"sm" | "md" | "lg"'sm'TextInput-aligned height, font, padding, and icon scale; includes lg
variantTextFieldVariant'outline'Same variant chrome as TextInput. Focus matches hover without a focus ring; trueGhost stays chrome-free.
widthstring'6rem'CSS inline size for the wrapper, such as 8rem or 100%
buttonLayout"horizontal" | "vertical"'vertical'Button arrangement: vertical (stacked on right) or horizontal (left/right)
disabledbooleanfalseDisables the input and buttons
classClassValue—Additional CSS classes
stylestring—Inline styles on the component styling target described below.
idstring—HTML id attribute
namestring—HTML name attribute for forms
elementbindableHTMLInputElement—Bindable reference to the underlying input element

…rest: Additional attributes forwarded to the inner <input> (e.g. aria-label, autocomplete).

Usage tips

  • Hold down the +/- buttons for continuous increment - useful for large ranges.
  • Arrow Up / Arrow Down keys work when the input is focused.
  • Use width to control the wrapper size - defaults to 6rem which works well for most counters.
  • Always set min and max when the domain has natural bounds to prevent invalid values.
  • Non-numeric manual input resolves to min when set, otherwise 0 - validate in your form layer if you need stricter behavior.

Styling

.ph-number-input is the stable root identification hook. Variant chrome and size configuration use the shared .ph-text-field primitive; anatomy stays in scoped CSS; data-size always identifies the selected size. class and style apply to the root shell; native attributes, attachments, and bind:element target the input. data-variant exposes outline, fill, ghost, or trueGhost; data-layout exposes vertical or horizontal. Heights use --ph-comp-h-sm (1.5rem), --ph-comp-h-md (1.75rem), and --ph-comp-h-lg (2rem), with the corresponding --ph-comp-icon-* tokens for horizontal icons. Font sizes (0.75rem / 0.875rem / 1rem) and input padding (0.375rem / 0.5rem / 0.625rem) match TextInput. The default size remains sm. The default width remains 6rem. Set width="8rem", width="100%", or a CSS expression; width class strings are no longer supported. style="inline-size: 8rem" remains available. Internal part selectors and --_ph-* properties are implementation details.

NumberInput, TextInput, and Textarea share .ph-text-field for variant chrome and size configuration. Their radius uses --ph-field-radius (0.5rem); outline shadows use --ph-input-shadow. Focus uses the same appearance as hover without a blue or accent-colored focus ring, including the step buttons. trueGhost has no border, fill, shadow, or hover/focus chrome. A disabled step button at a min/max bound does not suppress an enabled field’s hover/focus appearance.

outline has a quiet translucent background, muted border, and input shadow. fill uses the stronger neutral control background with no visible border or shadow; the distinction remains on hover and focus.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.