State & binding
Every prime-ui value control manages its value with standard Svelte 5 bindings: Checkbox, Input, NumberInput, RadioGroup, Select. There are two modes. The examples use Checkbox, but the same applies to value on the others.
Two-way binding
Section titled “Two-way binding”bind: the value and the component keeps your state in sync. This is the simplest option and the right default.
<script lang="ts"> import { Checkbox } from "@viamrobotics/prime-ui";
let checked = $state(false);</script>
<Checkbox bind:checked />Fully controlled
Section titled “Fully controlled”Give bind: a function binding: a getter and a setter. Your setter is the single source of truth, so it can transform or veto a change: if it doesn’t update the state, nothing changes. It also runs on every user-initiated change, so it doubles as an “on change” hook.
<script lang="ts"> import { Checkbox } from "@viamrobotics/prime-ui";
let checked = $state(false);</script>
<!-- only allow turning it on, never off --><Checkbox bind:checked={() => checked, (next) => { if (next) checked = next; }} />To react to changes without controlling them, use $effect. It also fires on programmatic changes:
$effect(() => console.log("checked is now", checked));NumberInput binds number | undefined, and undefined means the field is empty. FileInput binds a File[], and a cleared input is an empty array. Input, RadioGroup, and Select bind string. Checkbox binds checked, a boolean.
Two things Svelte cannot do for you:
- A component cannot tell whether a prop is bound or merely passed.
<Input value={name} />rendersnameand lets the user type past it, with nothing written back. If you want the value kept,bind:it. If you want it pinned, use the function binding. - Native
bind:valuereads the input’s runtimetype, not the TypeScript type.Inputtherefore accepts only the types whose value is a string.numberandrangeyield a number, so they areNumberInput, andcheckbox,radio, andfilebind something other thanvalue.
Native event handlers
Section titled “Native event handlers”Input and NumberInput render a real <input>, so alongside bind:value they accept every native handler, oninput, onchange, onblur, onfocus, and the rest, for side effects and focus handling.
<Input bind:value onblur={() => validate(value)} />Checkbox, RadioGroup.Item, and Select.Trigger render a real <button>, so onfocus, onblur, onclick, and onkeydown land on it. Your handler runs first, and preventDefault() in it stops the widget’s. These controls never fire change or input, since no native control changes underneath. React to a value change with the function binding or $effect.
<Checkbox bind:checked onblur={() => (touched = true)} />Two things to know:
focusandblurdo not bubble. Anonbluron theRadioGrouproot<div>never fires, since the div itself is never focused. Useonfocusinandonfocusouton the group, exactly as you would on a native<fieldset>.Selectrenders no element, so it takes no handlers and noclass. Put them onSelect.Trigger.