use-form-field-props

Derive the default control id for a path.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { formFieldId, toFormFieldErrors, useFormErrorSummaryFields, useFormFieldProps } from "@vizejs/composable/use-form-field-props";

Try it

Wire a field to its label and error

Generate the ids and ARIA attributes that connect a label, input and error message.

Open the interactive example

What to observe: Subscribe with an incomplete address shows the error and marks the input invalid. A complete address clears it.

Spread labelProps, fieldProps and errorMessageProps onto the elements. Pair it with useForm, which owns values and validation.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useForm } from "@vizejs/composable/use-form";
import { useFormFieldProps } from "@vizejs/composable/use-form-field-props";

const form = useForm({
  initialValues: { email: "" },
  validateOn: "submit",
  revalidateOn: "change",
  validators: {
    email: (value) =>
      /^[^\s@]+@[^\s@]+$/.test(value) ? undefined : "Enter a complete email address.",
  },
});
const email = useFormFieldProps(form, "email", { idPrefix: "newsletter" });
const { value } = email.field;
const subscribe = form.handleSubmit(() => undefined);
</script>

<template>
  <form class="composable-example" novalidate @submit="subscribe">
    <p>Wire a label, input and error message together with the right ARIA attributes.</p>
    <label v-bind="email.labelProps.value">
      Newsletter email
      <input v-model="value" type="email" v-bind="email.fieldProps.value" />
    </label>
    <p v-bind="email.errorMessageProps.value">{{ email.errorMessage.value }}</p>
    <button type="submit">Subscribe</button>
  </form>
</template>

Runtime contract

API

formFieldId

Derive the default control id for a path.

function formFieldId(path: string, idPrefix = "field"): string

useFormFieldProps

Bind one useForm field to accessible field markup and any v-model control. Returns ids, ARIA relations (fieldProps), label/description/error props, and modelProps whose shapes match @vizejs/ui's Field contracts structurally, so the bridge lives here without a runtime dependency on the UI package. Ids are derived from the path, so server and client agree without any instance-local id sequence. Server rendering: pure derived state, no host access. Cleanup: none needed beyond the owning form.

function useFormFieldProps<Values extends object, Output, Path extends FormPath<Values>>( form: FormControls<Values, Output>, path: Path, options: UseFormFieldPropsOptions = {}, ): FormFieldPropsControls<FormPathValue<Values, Path>, Path>

<script setup lang="ts">
const form = useForm({ initialValues: { address: { city: "" } } });
const city = useFormFieldProps(form, "address.city");
</script>
<template>
  <label v-bind="city.labelProps.value">City</label>
  <TextInput v-bind="city.controlProps.value" />
  <p v-if="city.invalid.value" v-bind="city.errorMessageProps.value">{{ city.errorMessage.value }}</p>
</template>

toFormFieldErrors

Convert form errors into ui FormFieldError entries ({ name, message, path }), one per message, so @vizejs/ui Field components match them by name.

function toFormFieldErrors( errors: Readonly<Record<string, readonly string[]>>, ): readonly FormFieldErrorEntry[]

useFormErrorSummaryFields

Derive @vizejs/ui ErrorSummary fields from a useForm instance. Each invalid path becomes { id, message, label? } pointing at the control id that useFormFieldProps assigns, in order then error order. Server rendering: pure derived state. Cleanup: none.

function useFormErrorSummaryFields<Values extends object, Output>( form: FormControls<Values, Output>, options: UseFormErrorSummaryFieldsOptions<Values> = {}, ): ComputedRef<readonly FormErrorSummaryItem[]>

<ErrorSummary :fields="summary" heading="Fix these fields" />

Types

FormFieldControlProps

Accessible relations for a form control. Structurally identical to FieldControlProps from @vizejs/ui/field-wiring, so the object can be bound with v-bind onto any @vizejs/ui control (or a native element) without this package depending on @vizejs/ui.

FormFieldLabelProps

Props for a <label> (or ui FieldLabel) element.

FormFieldTextProps

Props for description and error-message elements.

FormFieldModelProps

v-model bindings for any component that follows the modelValue / update:modelValue convention, plus a blur listener that marks the field touched (and validates on blur when the form is configured to).

UseFormFieldPropsOptions

Options for useFormFieldProps.

FormFieldPropsControls

Bindings returned by useFormFieldProps.

FormErrorSummaryItem

One invalid field, structurally identical to ErrorSummaryField from @vizejs/ui/error-summary.

FormFieldErrorEntry

One error, structurally identical to FormFieldError from @vizejs/ui/form, so ui Field components match errors by name.

UseFormErrorSummaryFieldsOptions

Options for useFormErrorSummaryFields.