API

The Soupcon component and the props it takes.

Anatomy#

Import Soupcon and give it a label, a value and a change handler.

import { Soupcon } from "soupcon/react";

<Soupcon label="W" value={width} onValueChange={setWidth} />;

It renders a label holding the drag handle, the input and the unit.

<label data-soupcon-root>
	<span data-soupcon-label>W</span>
	<input data-soupcon-input />
	<span data-soupcon-unit>px</span>
</label>

Props#

PropTypeDefault
labelReactNodeRequired
valuenumberRequired
onValueChange(value: number) => voidRequired
onValueCommit(value: number) => void-
minnumber-
maxnumber-
stepnumber1
perPxnumberstep
precisionnumber-
unitstring-
localestringThe browser's
disabledbooleanfalse
readOnlybooleanfalse
pointerLockbooleantrue

label#

The drag handle. If it's an icon, also pass aria-label.

onValueChange#

Called for every change, including each step of a drag.

onValueCommit#

Called once when a change is finished: at the end of a drag, when typed text is applied, or when the arrow keys are released. It doesn't fire if the value ended up where it started. Use it for undo history.

step#

The smallest change a drag or arrow key snaps to. Typed values can land between steps.

perPx#

How much the value changes per pixel dragged. See Scrubbing.

precision#

The most decimal places the value can have. Without it, the field shows one more decimal than step has, so fine steps still show.

unit#

Shown after the value, and allowed after a typed number.

readOnly#

Allows focus and selecting the text, but no changes. disabled blocks everything.

Other props#

The ref, ARIA props, id and name go to the input. Everything else, like className, goes to the root.

const input = useRef<HTMLInputElement>(null);

<Soupcon ref={input} id="width" className="field" {...props} />;

Accessibility#

The input is a spinbutton with its range and current value set, and the unit is read along with the value. The drag handle is for pointers only, as keyboard users step with the arrow keys.

Good to know#