Number Field <mv-number-field>
Zahleneingabe mit − / + Buttons (gedrückt halten beschleunigt), Grenzen und Schrittweite, Pfeiltasten und Mausrad, Intl-Formatierung (Währung, Prozent, Einheit) und einem „Scrub“-Label: horizontal ziehen, um den Wert zu ändern, optional mit Pointer Lock.
| Kategorie | Formulare |
|---|---|
| Typ | Web Component (<mv-number-field>) |
| Status | stabil |
| Keywords | number, stepper, spinbutton, currency, percent, scrub, intl, form-associated |
When to use
- A bounded number like a count, percentage or price must be typed or nudged with - and + buttons
- The value should be displayed formatted as currency, percent or a unit while submitting the raw number
- Power users benefit from dragging the label to scrub the value quickly
Avoid when
- It is a product quantity on a cart line or product page with stock limits → use Quantity instead
- A compact design-tool inspector needs scrubbing, expressions and units → use Scrub Field instead
- The exact value matters less than a rough position within a range → use Slider instead
Installation
node scripts/add.mjs number-field --out ./src/marvelousKI-Agent mit dem MCP-Server von Marvelous UI: install_components({ slugs: ["number-field"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).
Kopierte Dateien (inklusive Abhängigkeiten): tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/i18n.js, core/motion.js, components/number-field/number-field.js, components/number-field/number-field.css.
Verwendung
Referenz-Markup zum Starten und Anpassen mit Attributen, data-* und CSS-Variablen:
<form id="number-field-demo-form" style="display:grid;grid-template-columns:repeat(2,minmax(0,10.5rem));gap:1.25rem 1.5rem;justify-content:center">
<mv-number-field label="Quantity" name="quantity" value="2" min="1" max="20" style="--mv-number-field-width:100%"></mv-number-field>
<mv-number-field label="Unit price" name="price" value="24.9" min="0" step="0.5" format="currency" currency="USD" wheel style="--mv-number-field-width:100%"></mv-number-field>
<mv-number-field label="Discount" name="discount" value="0.15" min="0" max="0.5" step="0.05" format="percent" layout="stacked" style="--mv-number-field-width:100%"></mv-number-field>
<mv-number-field id="number-field-demo-weight" label="Weight" name="weight" value="2.4" min="0" max="30" step="0.1" format="unit" unit="kilogram" scrub pointer-lock style="--mv-number-field-width:100%"></mv-number-field>
<p style="grid-column:1/-1;margin:0;text-align:center;font-size:.75rem;color:var(--mv-fg-muted)">Hold − / + to repeat · ↑/↓ on the keyboard (Shift ×10) · drag the “Weight” label horizontally.</p>
</form>API
Attributes
| Name | Typ | Standard | Beschreibung |
|---|---|---|---|
label | string | Built-in label (also acts as the “scrub” area). | |
name | string | Form field name (raw numeric value, e.g. “0.15”). | |
value | number | Initial value (also used on reset). | |
min / max | number | Bounds; the value is clamped and buttons disable at the limits. | |
step | number | 1 | Step (also sets the precision). |
large-step | number | step × 10 | Step with Shift, Page↑/Page↓. |
format | decimal | currency | percent | unit | decimal | Intl.NumberFormat style (percent: 0.15 displays as “15%”). |
currency | string | USD | ISO 4217 code for format=currency. |
unit | string | Intl unit for format=unit (kilogram, centimeter, liter…). | |
decimals | number | Fixed number of displayed decimals. | |
locale | string | en-US | Formatting and input locale (both “,” and “.” are accepted). The value auto follows the page language (nearest lang); without the attribute, en-US unless the app registered the page language with setStrings() (core/i18n.js). |
layout | split | stacked | split | − / + on either side, or chevrons stacked on the right. |
wheel | boolean | The mouse wheel changes the value while the field has focus. | |
scrub | boolean | Dragging horizontally on the label changes the value (Shift ×10, Alt ×0.1). | |
pointer-lock | boolean | Locks the pointer while scrubbing (infinite drag + virtual cursor). | |
scrub-pixels | number | 4 | Pixels of movement per step. |
placeholder | string | Text shown when empty. | |
required / disabled / readonly / invalid | boolean | Form states. | |
data-size | sm | lg | Height. |
Properties
| Name | Typ | Beschreibung |
|---|---|---|
value | number | null | Numeric value. |
valueAsNumber | number | Value or NaN. |
strings | Partial<Record<string, string>> | Overrides for the default text (en-US): decrease and increase (stepper button labels), valueMissing (required message). App-wide translations: setStrings() from core/i18n.js, under the key "number-field". Can be set before the element is defined. |
Methods
| Name | Beschreibung |
|---|---|
stepUp(n) / stepDown(n) | Adds / removes n steps. |
focus() | Focuses the input. |
checkValidity() / reportValidity() | Native validation. |
Events
| Name | Beschreibung |
|---|---|
mv-change | detail: { value, formatted } on every committed change (step, typing, scrub). |
Content structure
| Name | Beschreibung |
|---|---|
[data-scrub] | Extra child element used as a scrub area. |
CSS classes
| Name | Beschreibung |
|---|---|
mv-number-field-label / -group / -input / -btn / -cursor | Generated parts; data-scrubbing while dragging. |
CSS variables
| Name | Standard | Beschreibung |
|---|---|---|
--mv-number-field-width | 9.5rem | Width. |
--mv-number-field-radius | var(--mv-radius-md) | Group radius. |
Accessibility
APG Spinbutton pattern: the input has role=spinbutton, aria-valuenow, aria-valuetext (formatted value, e.g. “$24.90”), aria-valuemin/max, and the name of the built-in or associated <label>. ↑/↓ (Shift ×10), Page↑/↓, Home/End (bounds), Enter commits, Escape cancels typing. The −/+ buttons are out of the tab order (tabindex=-1) and labeled “Decrease” / “Increase”. Scrubbing is a pointer shortcut, never the only way to change the value.