use-field

A standalone validated field, independent of any form.


Package	`@vizejs/composable/use-field`
Own the source	`vize lib pull composable:use-field`
Runtime exports	`useField`
Gzip budget	3328 B

Usage

import { useField } from "@vizejs/composable/use-field";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useField`	state	experimental	safe	stable	reactive-scope	web, server, worker, native, desktop, terminal	`AbortController`, `DOMException`, `structuredClone`	`isStandardSchema`, `tryOnScopeDispose`, `validateStandardSchema`

API

`useField`

A standalone validated field, independent of any form. Rules may be plain (a)synchronous validators or Standard Schema v1 validators (anything with a ~standard property). A newer validation aborts older ones through their signal, and stale results are ignored. With validateOn: "change" validation runs after each value change, never during setup, so server-rendered markup matches the first client render. For multi-field state use useForm. Server rendering: pure state; nothing validates during setup. Pending validations are aborted when the owning scope stops.

function useField<Value>( initialValue: Value | (() => Value), options: UseFieldOptions<NoInfer<Value>> = {}, ): FieldControls<Value>

const email = useField("", {
  name: "email",
  rules: [(value) => (value.includes("@") ? undefined : "Invalid email")],
});

Types

`FieldRuleContext`

Context passed to standalone field validators.

Member	Type	Description
`signal`	`AbortSignal`	Aborted when a newer validation supersedes this one.

`UseFieldOptions`

Options for useField.

Member	Type	Description
`rules`?	`FieldRuleSource<Value> \| readonly FieldRuleSource<Value>[]`	Validators run in order; their messages are concatenated.
`validateOn`?	`FieldValidationTrigger`	When validation runs automatically.
`name`?	`string`	Field name exposed for `name` attributes and error summaries.

`FieldControls`

Reactive state and actions returned by useField.

Member	Type	Description
`name`	`string`	Field name.
`value`	`Ref<Value>`	Writable value (use with `v-model`).
`errors`	`Readonly<ShallowRef<readonly string[]>>`	Current error messages.
`error`	`ComputedRef<string \| undefined>`	First error message.
`valid`	`ComputedRef<boolean>`	Whether no errors are recorded.
`dirty`	`ComputedRef<boolean>`	Whether the value differs from the initial value.
`touched`	`Readonly<Ref<boolean>>`	Whether the field was blurred.
`validating`	`Readonly<Ref<boolean>>`	Whether a validation is pending.
`onBlur`	`() => void`	Mark the field touched (wire to `blur`); validates when configured.
`validate`	`() => Promise<boolean>`	Run every rule, aborting an older validation still in flight.
`setErrors`	`(errors: readonly string[]) => void`	Replace errors (for example with server errors).
`reset`	`(value?: Value) => void`	Restore the initial value (or install a new one) and clear state.