Prepare the record
Aliquot / Sample 042
Quantity field
A 44px Vlak numeric input and styled unit selector with controlled quantity values, form submission and reset support.
Preview
In action
When to use
Use it for
- Dimensioned quantities with explicit unit choices and native numeric constraints.
- name submits the amount and unitName submits the unit, defaulting to name followed by .unit.
- Supply value and onValueChange when the application converts units or persists the result; unit selection alone keeps the supplied amount unchanged.
- null represents a missing amount or unit. Unit option values must be unique and non-empty.
Not for
- Assuming that choosing a different unit automatically converts the amount.
- Relying on formatting to establish scientific precision or dimensional compatibility.
Install
Three ways in. They share one source, so the pixels match whichever you pick.
1. Import the package
npm install @noorddev/vlak-react
// once, next to your app's root
import "@noorddev/vlak-react/css";
import { QuantityField } from "@noorddev/vlak-react";Precompiled React and one stylesheet. No compiler to configure. Per-component imports work too: @noorddev/vlak-react/components/quantity-field.
2. Vendor the source
npx @noorddev/vlak-cli add quantity-field
The StyleX leaf lands in components/vlak/ with its dependencies, for your own compiler to own. See StyleX.
3. Through shadcn
npx shadcn add https://vlak.dev/r/quantity-field.json
The same registry item, installed by shadcn's CLI.
CSS only
<link rel="stylesheet" href="node_modules/@noorddev/vlak/css/vlak.css" />
No React. Link vlak.css and use the markup and classes below.
React
import { QuantityField } from "@noorddev/vlak-react";
<QuantityField label="Sample volume" name="volume" units={[{ value: "ul", label: "µL" }, { value: "ml", label: "mL" }]} defaultValue={{ amount: 250, unit: "ul" }} min={0} required description="Enter the amount and its unit" />Props
QuantityField
A native numeric input and unit selector. Selection never converts the amount.
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | ReactNode | ||
unitsrequired | readonly QuantityUnit[] | ||
value | QuantityValue | ||
defaultValue | QuantityValue | { amount: null, unit: null } | |
onValueChange | (value: QuantityValue) => void | Requests a quantity change. A unit change preserves the amount; the host owns conversion. | |
description | ReactNode | ||
unitName | string | name ? `${name}.unit` : undefined | Input names: name submits the amount; unitName defaults to name + '.unit'. |
amountLabel | string | "Amount" | |
unitLabel | string | "Unit" | |
unitPlaceholder | string | "Choose unit" | |
min | number | ||
max | number | ||
step | number | "any" | "any" | |
required | boolean | ||
readOnly | boolean | false |
Also accepts Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "defaultValue">.
Keyboard
| Keys | Does |
|---|---|
| Tab | Moves between the amount input and unit selector. |
| Arrow keys | Uses native number stepping or opens and navigates the Vlak unit selector. Enter or Space confirms a unit; Escape closes its menu. |
Accessibility
- A fieldset and legend name the quantity. Vlak Input and Select have visible labels, descriptions and 44px targets.
- Required, min, max and step use native validation. Invalid supplied numbers and unknown units have explicit text states.
- Native form reset restores uncontrolled defaults and leaves controlled values with the application.
- Read-only quantities preserve the submitted amount and unit while preventing edits. Disabled quantities do not submit.
- The fieldset ref and native attributes pass through; no unit is chosen implicitly.
Markup
<fieldset class="rs-quantity-field"><legend class="rs-quantity-field-legend">Sample volume</legend><div class="rs-quantity-field-row"><label class="rs-quantity-field-label">Amount<input class="rs-input rs-input-full rs-quantity-field-control" name="volume" type="number" step="any" value="250" /></label><div class="rs-quantity-field-label"><span id="quantity-unit-label">Unit</span><div class="rs-select rs-select-fluid"><button type="button" class="rs-dropdown" role="combobox" aria-labelledby="quantity-unit-label" aria-expanded="false" aria-haspopup="listbox"><span>µL</span></button></div></div></div></fieldset>
Classes
.rs-quantity-field.rs-quantity-field-legend.rs-quantity-field-row.rs-quantity-field-label.rs-quantity-field-control.rs-quantity-field-description