@viamrobotics/prime-controls
@viamrobotics/prime-controls is a set of compact realtime controls for tool panels. Each number control steps by keyboard and scrubs by dragging its label sideways, so a value can be tuned live without typing. Containers group the controls into panels, folders, and tabs.
NumberField, one number with a label that doubles as the scrub handle.TextField, one string with a plain label and no scrub.FileField, a native file input that shows the chosen file names and clears them.Point, a 2D, 3D, or 4D vector as oneNumberFieldper axis.Slider, a range input with aNumberFieldreadout beside it.Select, a compact dropdown for choosing one of a list of items.ToggleButtons, a compact row of mutually exclusive buttons.Panel,Folder, andTabs, the containers that group controls at tool panel scale.- A scrub or a drag writes the bound value on every pointer move, so a function binding sees each intermediate value.
- speed:
5 - position:
{"x":0,"y":1,"z":2} - opacity:
0.5 - intensity:
0.8 - exposure:
1 - projection:
perspective - mode:
move - step:
0.5 - angle:
15
Code
<script lang="ts"> import type { PointValue } from "@viamrobotics/prime-controls";
import { Folder, NumberField, Panel, Point, Select, Slider, Tabs } from "@viamrobotics/prime-controls";
let speed = $state(5); let position = $state<PointValue>({ x: 0, y: 1, z: 2 }); let opacity = $state(0.5); let intensity = $state(0.8); let exposure = $state(1); let mode = $state("move"); let moveStep = $state(0.5); let rotateStep = $state(15); let projection = $state("perspective"); const projections = [ { value: "perspective", label: "Perspective" }, { value: "orthographic", label: "Orthographic" }, ];</script>
<div class="not-content flex flex-wrap items-start gap-6"> <Panel title="Scene" class="w-80"> <NumberField label="Speed" bind:value={speed} /> <Point label="Position" step={0.1} bind:value={position} /> <Select items={projections} bind:value={projection} aria-label="Projection" /> <Slider label="Opacity" min={0} max={1} step={0.01} bind:value={opacity} /> <Folder title="Lighting"> <Slider label="Intensity" min={0} max={1} step={0.01} bind:value={intensity} /> <NumberField label="Exposure" step={0.1} bind:value={exposure} /> </Folder> <Tabs bind:value={mode}> <Tabs.List aria-label="Mode"> <Tabs.Trigger value="move">Move</Tabs.Trigger> <Tabs.Trigger value="rotate">Rotate</Tabs.Trigger> </Tabs.List> <Tabs.Content value="move"> <NumberField label="Step" step={0.1} bind:value={moveStep} /> </Tabs.Content> <Tabs.Content value="rotate"> <NumberField label="Angle" bind:value={rotateStep} /> </Tabs.Content> </Tabs> </Panel> <ul class="m-0 list-none p-0 text-sm text-subtle-2"> <li>speed: <code>{speed}</code></li> <li>position: <code>{JSON.stringify(position)}</code></li> <li>opacity: <code>{opacity}</code></li> <li>intensity: <code>{intensity}</code></li> <li>exposure: <code>{exposure}</code></li> <li>projection: <code>{projection}</code></li> <li>mode: <code>{mode}</code></li> <li>step: <code>{moveStep}</code></li> <li>angle: <code>{rotateStep}</code></li> </ul></div>Installation
Section titled “Installation”-
Install the package and its peers. The
sveltepeer is^5.29.0.Terminal window pnpm add @viamrobotics/prime-controls @viamrobotics/prime-ui @viamrobotics/tailwind-configTerminal window npm install @viamrobotics/prime-controls @viamrobotics/prime-ui @viamrobotics/tailwind-configTerminal window yarn add @viamrobotics/prime-controls @viamrobotics/prime-ui @viamrobotics/tailwind-config -
Import the stylesheets once, in this order. Tailwind skips
node_moduleswhen it scans for classes, so each package’s stylesheet points it at that package’s compiled components.@import "tailwindcss";@import "@viamrobotics/prime-ui/styles.css";@import "@viamrobotics/prime-controls/styles.css";
NumberField
Section titled “NumberField”NumberField wraps a native <input type="number"> with an optional visible label. Without a label, pass aria-label or aria-labelledby, and the field does not scrub.
Two-way binding
Section titled “Two-way binding”bind:value holds the number, or undefined while the field is empty. Drag the label sideways to scrub, or focus the input and press the arrow keys.
speed: 5
Code
<script lang="ts"> import { NumberField } from "@viamrobotics/prime-controls";
let speed = $state(5);</script>
<div class="not-content flex w-48 flex-col gap-3"> <NumberField label="Speed" bind:value={speed} /> <p class="text-sm text-subtle-2">speed: <code>{speed}</code></p></div>Function binding
Section titled “Function binding”A scrub writes on every pointer move, so a function binding receives each intermediate value. Use one to throttle, to veto by not assigning, or to count writes as this recipe does.
last value: 5
writes: 0
Code
<script lang="ts"> import { NumberField } from "@viamrobotics/prime-controls";
let speed = $state(5); let writes = $state(0);</script>
<div class="not-content flex w-48 flex-col gap-3"> <NumberField label="Speed" bind:value={ () => speed, (next) => { if (next !== undefined) speed = next; writes += 1; } } /> <p class="text-sm text-subtle-2">last value: <code>{speed}</code></p> <p class="text-sm text-subtle-2">writes: <code>{writes}</code></p></div>Range and step
Section titled “Range and step”min and max clamp scrubs and key presses, while typing stays unclamped. step is the amount one key press or one pixel of scrub moves the value, and a fractional step keeps its decimal places, so 0.05 steps never show float residue.
opacity: 0.5
Code
<script lang="ts"> import { NumberField } from "@viamrobotics/prime-controls";
let opacity = $state(0.5);</script>
<div class="not-content flex w-48 flex-col gap-3"> <NumberField label="Opacity" min={0} max={1} step={0.05} bind:value={opacity} /> <p class="text-sm text-subtle-2">opacity: <code>{opacity}</code></p></div>Keyboard and pointer
Section titled “Keyboard and pointer”| Input | Action |
|---|---|
| Arrow Up / Arrow Down | Raise or lower the value by step |
| Shift + Arrow Up / Arrow Down | Step by 10 times step |
| Alt + Arrow Up / Arrow Down | Step by a tenth of step |
| Drag the label sideways | Scrub, moving the value by step for each pixel |
| Shift or Alt while scrubbing | Scale each pixel by 10 or by a tenth |
| Click the label | Focus the input |
| Slider: Arrow Left / Right / Up / Down | The range moves by step, natively |
| Slider: Home / End | The range jumps to min or max, natively |
| Slider: readout | Steps like a NumberField, without scrubbing |
A drag begins once the pointer moves 4 pixels from where it was pressed, and only the primary button scrubs. A disabled or readonly field neither steps nor scrubs. An empty field starts from min, or 0 without one.
Point binds a PointValue, an object with x and y and optionally z and w. The defined axes decide how many fields render. Each axis letter sits inside its field as a prefix and is the scrub handle. Editing one axis writes a new object with that axis changed and the others as they were. min, max, step, and disabled apply to every axis.
{"x":0,"y":0}
Code
<script lang="ts"> import type { PointValue } from "@viamrobotics/prime-controls";
import { Point } from "@viamrobotics/prime-controls";
let offset = $state<PointValue>({ x: 0, y: 0 });</script>
<div class="not-content flex w-64 flex-col gap-3"> <Point label="Offset" bind:value={offset} /> <p class="text-sm text-subtle-2"><code>{JSON.stringify(offset)}</code></p></div>Define z and a third field appears.
{"x":0,"y":1,"z":2}
Code
<script lang="ts"> import type { PointValue } from "@viamrobotics/prime-controls";
import { Point } from "@viamrobotics/prime-controls";
let position = $state<PointValue>({ x: 0, y: 1, z: 2 });</script>
<div class="not-content flex w-80 flex-col gap-3"> <Point label="Position" step={0.1} bind:value={position} /> <p class="text-sm text-subtle-2"><code>{JSON.stringify(position)}</code></p></div>Define w as well for a fourth.
{"x":0,"y":0,"z":0,"w":1}
Code
<script lang="ts"> import type { PointValue } from "@viamrobotics/prime-controls";
import { Point } from "@viamrobotics/prime-controls";
let rotation = $state<PointValue>({ x: 0, y: 0, z: 0, w: 1 });</script>
<div class="not-content flex w-96 flex-col gap-3"> <Point label="Rotation" step={0.01} min={-1} max={1} bind:value={rotation} /> <p class="text-sm text-subtle-2"><code>{JSON.stringify(rotation)}</code></p></div>Function binding
Section titled “Function binding”The setter receives the whole new PointValue. This one refuses any value farther than 10 from the origin by not assigning, so the point stops at that circle while the drag continues.
{"x":0,"y":0}
rejected writes: 0
Code
<script lang="ts"> import type { PointValue } from "@viamrobotics/prime-controls";
import { Point } from "@viamrobotics/prime-controls";
let position = $state<PointValue>({ x: 0, y: 0 }); let rejected = $state(0);
const MAX_DISTANCE_FROM_ORIGIN = 10;</script>
<div class="not-content flex w-64 flex-col gap-3"> <Point label="Position" bind:value={ () => position, (next) => { if (Math.hypot(next.x, next.y) > MAX_DISTANCE_FROM_ORIGIN) { rejected += 1; return; } position = next; } } /> <p class="text-sm text-subtle-2"><code>{JSON.stringify(position)}</code></p> <p class="text-sm text-subtle-2">rejected writes: <code>{rejected}</code></p></div>Custom labels
Section titled “Custom labels”labels renames any axis letter, and an axis left out keeps its uppercase name.
{"x":255,"y":128,"z":0}
Code
<script lang="ts"> import type { PointValue } from "@viamrobotics/prime-controls";
import { Point } from "@viamrobotics/prime-controls";
let color = $state<PointValue>({ x: 255, y: 128, z: 0 });</script>
<div class="not-content flex w-80 flex-col gap-3"> <Point label="Color" labels={{ x: "R", y: "G", z: "B" }} min={0} max={255} bind:value={color} /> <p class="text-sm text-subtle-2"><code>{JSON.stringify(color)}</code></p></div>Per axis
Section titled “Per axis”axes lets single axes set min, max, step, suffix, state, and describedBy for themselves, and an axis listed there uses its own value in place of the control’s. So a vector whose last axis has its own unit and range is still one Point. This orientation is four axes, and the last is an angle with its own step, range, and unit.
Code
<script lang="ts"> import { Point } from "@viamrobotics/prime-controls";
let orientation = $state({ x: 0, y: 0, z: 1, w: 90 });</script>
<div class="not-content w-96"> <Point label="Orientation" step={0.01} min={-1} max={1} labels={{ w: "θ" }} axes={{ w: { step: 1, min: -180, max: 180, suffix: "°" } }} bind:value={orientation} /></div>Details under an axis
Section titled “Details under an axis”The details snippet draws content under one axis field, at that field’s width, and receives the axis. Here each axis has a button that restores its live value. Y has been edited, so that one field warns through axes, and describedBy points it at the message under it. Pair a warn or error on one axis with such a message, because a color is never the only signal.
Differs from the live value.
Code
<script lang="ts"> import { mdiBackupRestore } from "@mdi/js"; import { Point, type PointAxis, type PointValue } from "@viamrobotics/prime-controls"; import { Icon } from "@viamrobotics/prime-ui";
const live: PointValue = { x: 312.4, y: -80.1, z: 420 }; const messageId = $props.id();
let target = $state<PointValue>({ x: 312.4, y: -75, z: 420 }); const edited = $derived(target.y !== live.y);
const restore = (axis: PointAxis) => { const value = live[axis]; if (value !== undefined) target = { ...target, [axis]: value }; };</script>
<div class="not-content w-96"> <Point label="Target" suffix="mm" step={0.1} axes={edited ? { y: { state: "warn", describedBy: messageId } } : undefined} bind:value={target} > {#snippet details(axis)} <button type="button" class="button w-full justify-start button-ghost button-xs" aria-label={`Reset ${axis.toUpperCase()} to its live value, ${live[axis]}`} onclick={() => restore(axis)} > <Icon icon={mdiBackupRestore} size="sm" /> {live[axis]} </button> {#if axis === "y" && edited} <p id={messageId} class="px-1.5 text-xs text-subtle-1">Differs from the live value.</p> {/if} {/snippet} </Point></div>NumberField, Point, Slider, ToggleButtons, and a Select with no children take a hint. It puts an info button beside the label that opens a tooltip with the text, and the control is described by the same text, tooltip open or not. The button is named About <label>. A hint needs a visible label, so it sits beside one. Select shows no label, so its button is named from aria-label. Point has one hint for the whole group, and its axis fields have none. An inset NumberField puts the button after the input, since the label is inside it.
Code
<script lang="ts"> import { NumberField, Panel, Point, Select, Slider, ToggleButtons, } from "@viamrobotics/prime-controls";
const spaces = [ { value: "local", label: "Local" }, { value: "world", label: "World" }, ]; const modes = [ { value: "move", label: "Move" }, { value: "rotate", label: "Rotate" }, ];
let power = $state(0.5); let position = $state({ x: 0, y: 1 }); let opacity = $state(1); let space = $state("local"); let mode = $state("move");</script>
<div class="not-content w-72"> <Panel title="Motor"> <NumberField label="Power" hint="Fraction of full power, from -1 to 1" min={-1} max={1} step={0.1} bind:value={power} /> <Point label="Target" hint="Where the motor should stop, in millimetres" bind:value={position} /> <Slider label="Opacity" hint="How much of the scene shows through" min={0} max={1} step={0.01} bind:value={opacity} /> <ToggleButtons label="Space" hint="The frame the target is measured in" items={spaces} bind:value={space} /> <Select aria-label="Mode" hint="What dragging the gizmo does" items={modes} bind:value={mode} /> </Panel></div>Suffix
Section titled “Suffix”NumberField takes a suffix, a short text such as a unit, drawn inside the input’s right edge in subtle-2. The input sits in a prime-ui Input.Group, which wears the border and the focus ring, and the input inside it goes borderless. An inset label keeps its left padding on the group. The suffix is part of the input’s accessible description, next to a hint and any aria-describedby you pass, so a unit is not only for sighted users. Point draws the suffix in every axis field, and Slider draws it in its readout.
Code
<script lang="ts"> import { NumberField, Point, Slider } from "@viamrobotics/prime-controls";
let length = $state(120); let position = $state({ x: 0, y: 1, z: 2 }); let opacity = $state(80);</script>
<div class="not-content flex w-72 flex-col gap-3"> <NumberField label="Length" suffix="mm" step={0.1} bind:value={length} /> <Point label="Position" suffix="mm" bind:value={position} /> <Slider label="Opacity" suffix="%" bind:value={opacity} /></div>NumberField, Point, and Slider take a state of 'none', 'info', 'warn', or 'error', prime-ui’s FieldState. 'warn' draws the warning-dark border. 'error' draws the danger-dark border and sets aria-invalid="true". 'info' changes no border, because prime-ui’s input style has no info rule, and this package draws none of its own. Point takes one state for the whole control and gives it to every axis field, and axes sets one on single axes. Slider draws its state on the readout, and an error marks the range invalid too. With a suffix, the border belongs to the group. A color is never the only signal, so pair a warn or error with text, such as a hint.
Code
<script lang="ts"> import { NumberField, Point, Slider } from "@viamrobotics/prime-controls";
let speed = $state(12); let length = $state(120); let position = $state({ x: 0, y: 1 }); let opacity = $state(40);</script>
<div class="not-content flex w-72 flex-col gap-3"> <NumberField label="Speed" state="warn" bind:value={speed} /> <NumberField label="Length" suffix="mm" state="error" bind:value={length} /> <Point label="Position" state="error" bind:value={position} /> <Slider label="Opacity" suffix="%" state="warn" bind:value={opacity} /></div>TextField
Section titled “TextField”TextField is a native text input with the NumberField row layout and no scrub. The label is a plain <label> that focuses the input. Without a label, pass aria-label or aria-labelledby. It takes placeholder, the native input attributes, hint, and state, which work as they do on NumberField. It has no suffix and no labelPlacement.
bind:value holds a string. Unlike NumberField, whose empty field is undefined, an empty TextField is the empty string, so a bound $state('') stays a string.
Name: "motion-1", pin: ""
Code
<script lang="ts"> import { TextField } from "@viamrobotics/prime-controls";
let name = $state("motion-1"); let pin = $state("");</script>
<div class="not-content flex w-72 flex-col gap-3"> <TextField label="Motion name" placeholder="builtin" bind:value={name} /> <TextField label="Pin" hint="The board pin to read, such as GPIO17" placeholder="GPIO17" bind:value={pin} /> <TextField label="Base name" state="error" value="" /> <p class="text-sm">Name: {JSON.stringify(name)}, pin: {JSON.stringify(pin)}</p></div>FileField
Section titled “FileField”FileField is prime-ui’s FileInput in the TextField row layout. A native <input type="file"> covers the control, so the picker, a dropped file, and the keyboard are the browser’s, and accept, multiple, and the other native attributes pass through. The label is a plain <label>. Without a label, pass aria-label or aria-labelledby. hint and state work as they do on NumberField.
bind:value holds a File[]. Without multiple it holds at most one file, and a cleared field is an empty array. The chosen names truncate to the row, so the control never grows past a narrow pane, and a clear button appears beside them. accept only filters the picker, so check the files yourself and set state="error" on one you refuse.
Audio: [], images: 0
Code
<script lang="ts"> import { FileField } from "@viamrobotics/prime-controls";
const SUPPORTED = [".wav", ".mp3"];
let audio = $state<File[]>([]); let images = $state<File[]>([]);
const unsupported = $derived( audio.some((file) => !SUPPORTED.some((extension) => file.name.toLowerCase().endsWith(extension))), );</script>
<div class="not-content flex w-80 flex-col gap-3"> <FileField label="Audio file" hint="A WAV or MP3 recording" accept={SUPPORTED.join(",")} state={unsupported ? "error" : "none"} bind:value={audio} /> <FileField label="Images" accept="image/*" multiple bind:value={images}>Choose images</FileField> <FileField label="Firmware" disabled /> <p class="text-sm"> Audio: {JSON.stringify(audio.map((file) => file.name))}, images: {images.length} </p></div>Panel is the dense container for a tool panel’s controls, a role="group" with a border and tight spacing. A visible title names the group. Without one, pass aria-label or aria-labelledby.
Code
<script lang="ts"> import { NumberField, Panel } from "@viamrobotics/prime-controls";
let width = $state(4); let height = $state(3);</script>
<div class="not-content flex flex-wrap items-start gap-4"> <Panel title="Size" class="w-56"> <NumberField label="Width" bind:value={width} /> <NumberField label="Height" bind:value={height} /> </Panel> <Panel aria-label="Size, no visible title" class="w-56"> <NumberField label="Width" bind:value={width} /> <NumberField label="Height" bind:value={height} /> </Panel></div>Folder
Section titled “Folder”Folder is a collapsible group inside a panel. Its title is the text of the button that opens and closes it. It is open by default, and bind:open reads and sets the state.
open: true
Code
<script lang="ts"> import { Folder, NumberField, Panel } from "@viamrobotics/prime-controls";
let open = $state(true); let gain = $state(1); let bias = $state(0);</script>
<div class="not-content flex w-64 flex-col gap-3"> <Panel title="Audio"> <Folder title="Mixer" bind:open> <NumberField label="Gain" step={0.1} bind:value={gain} /> <NumberField label="Bias" step={0.1} bind:value={bias} /> </Folder> </Panel> <p class="text-sm text-subtle-2">open: <code>{open}</code></p></div>Tabs is a compound of Tabs.List, Tabs.Trigger, and Tabs.Content. It wraps the prime-ui parts at panel scale, so the props and the keyboard behavior are prime-ui’s. bind:value holds the selected tab, and each Tabs.Content shows while its value is selected. Give Tabs.List an aria-label.
tab: position
Code
<script lang="ts"> import { NumberField, Panel, Tabs } from "@viamrobotics/prime-controls";
let tab = $state("position"); let x = $state(0); let angle = $state(0);</script>
<div class="not-content flex w-64 flex-col gap-3"> <Panel aria-label="Transform"> <Tabs bind:value={tab}> <Tabs.List aria-label="Transform mode"> <Tabs.Trigger value="position">Position</Tabs.Trigger> <Tabs.Trigger value="rotation">Rotation</Tabs.Trigger> </Tabs.List> <Tabs.Content value="position"> <NumberField label="X" step={0.1} bind:value={x} /> </Tabs.Content> <Tabs.Content value="rotation"> <NumberField label="Angle" bind:value={angle} /> </Tabs.Content> </Tabs> </Panel> <p class="text-sm text-subtle-2">tab: <code>{tab}</code></p></div>Select
Section titled “Select”Select is prime-ui’s Select at panel scale, with the same parts and keyboard. bind:value holds the selected item’s value. A Select with no children renders the trigger, the value, and the list from items. It takes placeholder and needs an aria-label or aria-labelledby.
mode: orbit
Code
<script lang="ts"> import { Panel, Select } from "@viamrobotics/prime-controls";
const modes = [ { value: "orbit", label: "Orbit" }, { value: "fly", label: "Fly" }, { value: "walk", label: "Walk" }, ];
let mode = $state("orbit");</script>
<div class="not-content flex w-64 flex-col gap-3"> <Panel aria-label="Camera"> <Select items={modes} bind:value={mode} aria-label="Mode" placeholder="Pick a mode" /> </Panel> <p class="text-sm text-subtle-2">mode: <code>{mode}</code></p></div>Write the parts when you need a class, handlers, or a custom item. Select.Items renders one compact item per entry of items.
mode: orbit
Code
<script lang="ts"> import { Panel, Select } from "@viamrobotics/prime-controls";
const modes = [ { value: "orbit", label: "Orbit" }, { value: "fly", label: "Fly" }, { value: "walk", label: "Walk" }, ];
let mode = $state("orbit");</script>
<div class="not-content flex w-64 flex-col gap-3"> <Panel aria-label="Camera"> <Select items={modes} bind:value={mode}> <Select.Trigger aria-label="Mode"> <Select.Value placeholder="Pick a mode" /> </Select.Trigger> <Select.Content> <Select.Viewport> <Select.Items /> </Select.Viewport> </Select.Content> </Select> </Panel> <p class="text-sm text-subtle-2">mode: <code>{mode}</code></p></div>ToggleButtons
Section titled “ToggleButtons”ToggleButtons is prime-ui’s ToggleButtons at panel scale, with the same keyboard. bind:value holds the selected option’s value, and one option is always selected. Give it items, or write ToggleButtons.Item parts when an option needs an icon or a class. The visible label names the group. Without it, pass aria-label or aria-labelledby.
space: local
Code
<script lang="ts"> import { Panel, ToggleButtons } from "@viamrobotics/prime-controls";
const spaces = [ { value: "local", label: "Local" }, { value: "world", label: "World" }, { value: "view", label: "View" }, ];
let space = $state("local");</script>
<div class="not-content flex w-64 flex-col gap-3"> <Panel aria-label="Transform"> <ToggleButtons items={spaces} bind:value={space} label="Space" /> </Panel> <p class="text-sm text-subtle-2">space: <code>{space}</code></p></div>Slider
Section titled “Slider”Slider pairs a native <input type="range"> with a NumberField readout. The visible label names both. Without it, pass aria-label or aria-labelledby. min, max, and step apply to both, and the readout steps like a NumberField without scrubbing. The readout is 64 px wide and grows to fit the longest value in the range, min or max at the step’s decimal places, so a value such as -179.9 is never clipped.
opacity: 0.5
Code
<script lang="ts"> import { Slider } from "@viamrobotics/prime-controls";
let opacity = $state(0.5);</script>
<div class="not-content flex w-72 flex-col gap-3"> <Slider label="Opacity" min={0} max={1} step={0.01} bind:value={opacity} /> <p class="text-sm text-subtle-2">opacity: <code>{opacity}</code></p></div>Function binding
Section titled “Function binding”A drag writes on every pointer move, so a function binding receives each intermediate value, as it does for NumberField. This one counts the writes.
last value: 20
writes: 0
Code
<script lang="ts"> import { Slider } from "@viamrobotics/prime-controls";
let level = $state(20); let writes = $state(0);</script>
<div class="not-content flex w-72 flex-col gap-3"> <Slider label="Level" bind:value={ () => level, (next) => { level = next; writes += 1; } } /> <p class="text-sm text-subtle-2">last value: <code>{level}</code></p> <p class="text-sm text-subtle-2">writes: <code>{writes}</code></p></div>NumberField
Section titled “NumberField”| Prop | Type | Default | Description |
|---|---|---|---|
bind:value | number | Current value. An empty field is undefined. | |
label | string | Visible label, rendered before the input. Dragging it sideways scrubs the value. Without
it, pass aria-label or aria-labelledby, and the field does not scrub. | |
hint | string | Help text, shown in a tooltip from an info button beside the label, and the control's
accessible description. Needs a visible label. | |
suffix | string | Short text such as a unit, drawn inside the input's right edge and part of the control's
accessible description. The input sits in a prime-ui Input.Group, which wears the border. | |
state | FieldState | Contextual state. warn draws the warning-dark border. error draws the danger-dark
border and sets aria-invalid. info changes no border. With a suffix, the group wears
the border. | |
min | number | The minimum value a scrub or a key press reaches. | |
max | number | The maximum value a scrub or a key press reaches. | |
step | number | 1 | The amount one key press or one pixel of scrub moves the value. Shift multiplies it by 10 and Alt by 0.1. |
labelPlacement | 'outside' | 'inset' | 'outside' | Where the visible label sits. 'outside' puts it before the input. 'inset' draws it
inside the input's left edge as a prefix, which fits a short label such as one axis
letter. |
class | ClassValue | Classes for the root element, which holds the label and the input. |
Plus everything in Omit<
HTMLInputAttributes,
'value' | 'min' | 'max' | 'step' | 'type' | 'children' | 'class'
>, spread onto the element.
Requires one of label, aria-label, or aria-labelledby.
TextField
Section titled “TextField”| Prop | Type | Default | Description |
|---|---|---|---|
bind:value | string | '' | Current text. An empty field is the empty string. |
label | string | Visible label, rendered before the input. Without it, pass aria-label or
aria-labelledby. | |
hint | string | Help text, shown in a tooltip from an info button beside the label, and the control's
accessible description. Needs a visible label. | |
state | FieldState | Contextual state. warn draws the warning-dark border. error draws the danger-dark
border and sets aria-invalid. info changes no border. | |
class | ClassValue | Classes for the root element, which holds the label and the input. |
Plus everything in Omit<HTMLInputAttributes, 'value' | 'type' | 'children' | 'class'>, spread onto the element.
Requires one of label, aria-label, or aria-labelledby.
FileField
Section titled “FileField”| Prop | Type | Default | Description |
|---|---|---|---|
bind:value | File[] | The chosen files, in the order the browser lists them. Without multiple it holds at most
one. A cleared field is an empty array. | |
label | string | Visible label, rendered before the input. Without it, pass aria-label or
aria-labelledby. | |
hint | string | Help text, shown in a tooltip from an info button beside the label, and the control's
accessible description. Needs a visible label. | |
placeholder | string | 'No file chosen' | Text shown while no file is chosen. |
clearLabel | string | 'Clear selection' | Accessible name of the button that clears the choice. |
state | FieldState | Contextual state. warn draws the warning-dark border. error draws the danger-dark
border and sets aria-invalid. info changes no border. | |
children | Snippet | Replaces the prompt, an upload icon and "Choose file". It is decoration, hidden from assistive technology, which reads the native input. | |
class | ClassValue | Classes for the root element, which holds the label and the input. |
Plus everything in Omit<
HTMLInputAttributes,
'value' | 'files' | 'type' | 'children' | 'class' | 'placeholder' | 'readonly'
>, spread onto the element.
Requires one of label, aria-label, or aria-labelledby.
| Prop | Type | Default | Description |
|---|---|---|---|
bind:value | PointValue | The vector. Its defined axes decide how many fields render. | |
label | string | Visible label for the group. Without it, pass aria-label or aria-labelledby. | |
hint | string | Help text, shown in a tooltip from an info button beside the label, and the control's
accessible description. The axis fields take none. Needs a visible label. | |
aria-label | string | Accessible name for the group when it has no visible label. | |
aria-labelledby | string | Id of the element that names the group when it has no visible label. | |
labels | Partial<Record<PointAxis, string>> | the uppercase axis name | Each axis field's visible label, which is also its scrub handle. |
min | number | The minimum value of every axis. | |
max | number | The maximum value of every axis. | |
step | number | 1 | The step of every axis. |
suffix | string | Text such as a unit, drawn inside the right edge of every axis field. | |
state | FieldState | Contextual state of the whole control, forwarded to every axis field. | |
axes | Partial<Record<PointAxis, PointAxisOptions>> | What single axes set for themselves: min, max, step, suffix, state, and
describedBy. An axis listed here uses its own value in place of the control's. | |
details | Snippet<[axis: PointAxis]> | Content drawn under one axis field, at that field's width, such as a restore button or a message about that axis. It receives the axis. | |
disabled | boolean | Disable every axis. | |
class | ClassValue | Classes for the root role="group" element. |
Requires one of label, aria-label, or aria-labelledby.
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | Visible title, which names the group. Without it, pass aria-label or aria-labelledby. | |
aria-label | string | Accessible name for the group when it has no visible title. | |
aria-labelledby | string | Id of the element that names the group when it has no visible title. | |
class | ClassValue | Classes for the root role="group" element. | |
children | Snippet | The panel's controls. |
Requires one of title, aria-label, or aria-labelledby.
Folder
Section titled “Folder”| Prop | Type | Default | Description |
|---|---|---|---|
title | string | Visible title, the text of the button that opens and closes the folder. | |
summary | string | Short text at the end of the title row, before the chevron, such as what the folder holds while it is closed. It is part of the button's accessible name. | |
bind:open | boolean | true | Whether the controls are shown. Two-way bindable. |
disabled | boolean | false | Disable the button that opens and closes the folder. |
class | ClassValue | Classes for the root element. | |
children | Snippet | The folder's controls. |
Slider
Section titled “Slider”| Prop | Type | Default | Description |
|---|---|---|---|
bind:value | number | Current value. | |
label | string | Visible label, rendered before the range. Without it, pass aria-label or aria-labelledby. | |
hint | string | Help text, shown in a tooltip from an info button beside the label, and the control's
accessible description. Needs a visible label. | |
aria-label | string | Accessible name for the range and the readout when there is no visible label. | |
aria-labelledby | string | Id of the element that names the range and the readout when there is no visible label. | |
min | number | 0 | The range's lowest value. |
max | number | 100 | The range's highest value. |
step | number | 1 | The amount one key press moves the value, and the granularity of a drag. |
suffix | string | Text such as a unit, drawn inside the right edge of the readout. | |
state | FieldState | Contextual state, drawn on the readout. warn draws the warning-dark border. error
draws the danger-dark border and sets aria-invalid on the range and the readout. info
changes no border. | |
disabled | boolean | Disable the range and the readout. | |
class | ClassValue | Classes for the root element, which holds the label, the range, and the readout. |
Requires one of label, aria-label, or aria-labelledby.
Takes extraClasses, children, ...restProps }: Props as its props.
Tabs.Content
The controls a Tabs strip shows while the tab with the same value is
selected.
Takes extraClasses, children, ...restProps }: Props as its props.
Tabs.List
The strip that holds a Tabs root’s triggers. Give it an aria-label or
aria-labelledby.
Takes extraClasses, children, ...restProps }: Props as its props.
Tabs.Trigger
One tab of a Tabs strip. Its children are the tab’s label.
Takes extraClasses, children, ...restProps }: Props as its props.
Select
Section titled “Select”Takes Props as its props.
Select.Content
The floating list of a Select, portaled to the body. Render a Select.Viewport inside it.
Plus everything in ComponentProps<typeof Select.Content>, spread onto the element.
Select.Group
A labeled set of items inside Select.Viewport. Start it with a Select.GroupHeading.
Plus everything in ComponentProps<typeof Select.Group>, spread onto the element.
Select.GroupHeading
The heading of a Select.Group, at a tool panel’s scale.
Takes extraClasses, children, ...restProps }: Props as its props.
Select.Item
One option of a Select, at a tool panel’s scale. Without children it shows its label
and a check when selected.
Takes extraClasses, ...restProps }: Props as its props.
Select.Items
One Select.Item per entry of the root’s items, at a tool panel’s scale.
Takes content }: Props as its props.
Select.ScrollDownButton
A control that scrolls the open list down, for lists taller than the viewport.
Plus everything in ComponentProps<typeof Select.ScrollDownButton>, spread onto the element.
Select.ScrollUpButton
A control that scrolls the open list up, for lists taller than the viewport.
Plus everything in ComponentProps<typeof Select.ScrollUpButton>, spread onto the element.
Select.Trigger
The button that opens a Select, at a tool panel’s scale. Its children are usually a
Select.Value.
Takes extraClasses, children, ...restProps }: Props as its props.
Select.Value
The selected item’s label inside Select.Trigger, or its placeholder when nothing is selected.
Plus everything in ComponentProps<typeof Select.Value>, spread onto the element.
Select.Viewport
The scrollable area inside Select.Content. Render Select.Items, or items and groups by hand.
Plus everything in ComponentProps<typeof Select.Viewport>, spread onto the element.
ToggleButtons
Section titled “ToggleButtons”| Prop | Type | Default | Description |
|---|---|---|---|
bind:value | string | The selected value. Two-way bindable. | |
items | ToggleButtonsOption[] | Options rendered as items, in order. Omit to compose ToggleButtons.Item children. | |
label | string | Visible label, rendered before the buttons. Without it, pass aria-label or aria-labelledby. | |
hint | string | Help text, shown in a tooltip from an info button beside the label, and the control's
accessible description. Needs a visible label. | |
aria-label | string | Accessible name for the group when there is no visible label. | |
aria-labelledby | string | Id of the element that names the group when there is no visible label. | |
disabled | boolean | Disable every option. | |
class | ClassValue | Classes for the root element, which holds the label and the buttons. | |
children | Snippet | ToggleButtons.Item parts, when items is omitted. |
Requires one of label, aria-label, or aria-labelledby.
ToggleButtons.Item
One option of a ToggleButtons group, at a tool panel’s scale. Its children are
the option’s content.
Takes extraClasses, children, ...restProps }: Props as its props.