Vue Form API

Reference every Form Vue component, prop, slot, event, function, and public type.

Back to the Vue forms guide

API

Vue package: @sectile/vue/form

Components

FormRoot
FormSelector
FormFieldSelector
FormField
FormLabel
FormDescription
FormMessage
FormSummary
FormReset
FormSubmit

Advanced control presets

compositeControlCapabilities
hiddenInputSubmissionCapabilities
hiddenSelectSubmissionCapabilities
hiddenValueSubmissionCapabilities
nativeInputControlCapabilities

Functions

`defineFormSubmission`

function defineFormSubmission<const Schema extends FormSchema<object, object>>(definition: FormSchemaSubmissionDefinition<Schema>): FormSchemaSubmissionDefinition<Schema>

`useFormSelector`

function useFormSelector<Selected>(selector: FormSelectorFunction<Selected>, options: FormSubscribeOptions<Selected> = {}): Readonly<ShallowRef<Selected>>

`useFormFieldSelector`

function useFormFieldSelector<Selected>(id: string, selector: FormFieldSelectorFunction<Selected>, options: FormSubscribeOptions<Selected> = {}): Readonly<ShallowRef<Selected>>

`useFormFieldController`

function useFormFieldController(id: string): FormFieldController

`provideFormControlOwner`

function provideFormControlOwner(): void

`useCompositeFormControl`

function useCompositeFormControl(options: {
  readonly root: FormElementSource;
  readonly focusTarget?: FormElementSource;
  readonly validationTarget?: FormElementSource;
  readonly submissions?: FormSubmissionSource;
  readonly labelMode?: FormLabelMode;
  readonly reset?: () => void;
  readonly getValue?: () => unknown;
  readonly isValueEqual?: (current: unknown, baseline: unknown) => boolean;
}): FormControlParticipation

`useFormControl`

function useFormControl(registration: FormControlRegistration): FormControlParticipation

`useNativeInputFormControl`

function useNativeInputFormControl(element: Readonly<ShallowRef<HTMLInputElement | HTMLTextAreaElement | null | undefined>>, options: {
    readonly reset?: () => void;
    readonly getValue?: () => unknown;
    readonly isValueEqual?: (current: unknown, baseline: unknown) => boolean;
  } = {}): FormControlParticipation

Props

`FormRootProps`

issues: Typereadonly FormIssueInput[] | undefinedDefault[]
Validation issues supplied by the application.
mapSubmitError: TypeFormSubmitErrorMapper | undefinedDefaultundefined
Maps a thrown or rejected submission error to a safe application-facing failure.
onSubmit: TypeFormSubmitHandler<Output> | undefinedDefaultundefined
Handles a validated native submission and may report success, a submission failure, or server issues.
revalidateOn: Typereadonly FormInteractionValidationTrigger[] | undefinedDefault['input']
Interaction events that rerun the active validation intent after validation fails.
schema: TypeFormSchema<Input, Output> | undefinedDefaultundefined
Standard Schema used for authoritative submission validation and output transformation.
validate: TypeFormValidateHandler<Input> | undefinedDefaultundefined
Validates the current field and returns application issues.
validateOn: Typereadonly FormInteractionValidationTrigger[] | undefinedDefault[]
Interaction events that run validation before the first submission attempt.

`FormFieldProps`

as: TypePrimitiveAs | undefinedDefaultundefined
Element or component rendered for this part.
asChild: Typeboolean | undefinedDefaultundefined
Whether to merge this part into its single child instead of rendering a wrapper.
disabled: Typeboolean | undefinedDefaultundefined
Whether interaction is unavailable.
form: Typestring | undefinedDefaultundefined
ID of the native form associated with the control.
id: Typestring | undefinedDefaultundefined
Stable ID used to connect related parts.
name: TypeFormFieldPath | undefinedDefaultundefined
Name used for native form submission.
readonly: Typeboolean | undefinedDefaultundefined
Whether the value can be inspected but not changed.
required: Typeboolean | undefinedDefaultundefined
Whether the control must contain a valid value before submission.

`FormSelectorProps`

equals: Type((previous: Selected, next: Selected) => boolean) | undefinedDefaultundefined
Returns whether two selected snapshots are equivalent.
select: TypeFormSelectorFunction<Selected>DefaultRequired
Selects the form or field state exposed to the slot.

`FormFieldSelectorProps`

equals: Type((previous: Selected, next: Selected) => boolean) | undefinedDefaultundefined
Returns whether two selected snapshots are equivalent.
id: TypestringDefaultRequired
Stable ID used to connect related parts.
select: TypeFormFieldSelectorFunction<Selected>DefaultRequired
Selects the form or field state exposed to the slot.

`FormPartProps`

as: TypePrimitiveAs | undefinedDefaultVaries by part
Element or component rendered for this part.
asChild: Typeboolean | undefinedDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.

Slots

`FormRootSlotProps`

dirty: Typeboolean
Whether the current value differs from its baseline.
reinitialize: TypeFormReinitializeAction
Adopts the current values as the new dirty baseline and resets form metadata unless preserved.
replaceIssues: TypeFormReplaceIssuesAction
Replaces validation issues for one source.
reset: TypeFormResetAction
Runs the native form reset and clears Form state; controlled values remain application-owned.
state: TypeFormState
Complete current form state.
submission: TypeFormSubmissionState
Current submission lifecycle snapshot.
submitCount: Typenumber
Number of submission attempts derived from submission.count.
submitFailed: TypeFormSubmitFailedAction
Marks the identified submission as failed.
submitStarted: TypeFormSubmitStartedAction
Starts submission and returns its generation token.
submitSucceeded: TypeFormSubmitSucceededAction
Marks the identified submission as successful.
submitted: Typeboolean
Whether submission has been attempted.
touched: Typeboolean
Whether the user has interacted with the field.
valid: Typeboolean
Whether current validation has no issues.
validation: TypeFormValidationState
Current validation lifecycle snapshot.

`FormFieldSlotProps`

clearIssues: Type(source?: FormIssueSource) => boolean
Clears validation issues for this field.
controlId: Typestring
ID assigned to the semantic control.
describedBy: Typestring
Space-separated IDs that describe the control.
descriptionId: Typestring
ID assigned to field help text.
dirty: Typeboolean
Whether the current value differs from its baseline.
id: Typestring
Stable ID for this field or item.
issues: Typereadonly FormIssue[]
Current canonical validation issues.
labelId: Typestring
ID assigned to the field label.
messageId: Typestring
ID assigned to the field error message.
relatedIssues: Typereadonly FormIssue[]
Issues owned elsewhere that also make this field invalid.
removeIssue: Type(issueId: string | number) => boolean
Removes one field issue by ID.
replaceIssues: Type(source: FormIssueSource, issues: readonly FormIssue[]) => boolean
Replaces validation issues for one source.
setMeta: Type(meta: FormFieldMetaInput) => boolean
Updates mutable metadata for this field.
touched: Typeboolean
Whether the user has interacted with the field.
upsertIssue: Type(issue: FormIssue) => boolean
Adds or replaces one field issue.
valid: Typeboolean
Whether current validation has no issues.

`FormSummarySlotProps`

firstIssue: TypeFormIssue | null
First canonical issue, or null.
issues: Typereadonly FormIssue[]
Current canonical validation issues.
serverIssues: Typereadonly FormIssue[]
Current canonical server issues.
submission: TypeFormSubmissionState
Current submission lifecycle snapshot.
valid: Typeboolean
Whether current validation has no issues.
validation: TypeFormValidationState
Current validation lifecycle snapshot.

`FormSubmitSlotProps`

canSubmit: Typeboolean
Whether the form is valid and not currently submitting.
submission: TypeFormSubmissionState
Current submission lifecycle snapshot.
submitting: Typeboolean
Whether form submission is currently in progress.
valid: Typeboolean
Whether current validation has no issues.

Events

`FormSubmitEvent`

Name	Type	Required
`formData`	`FormData`	Yes
`values`	`Readonly<Values>`	Yes
`submitter`	`HTMLElement \| null`	Yes
`state`	`FormState`	Yes
`reinitialize`	`(options?: FormReinitializeOptions) => void`	Yes
`nativeEvent`	`SubmitEvent`	Yes
`defaultPrevented`	`boolean`	Yes
`preventDefault`	`() => void`	Yes
`stopPropagation`	`() => void`	Yes
`stopImmediatePropagation`	`() => void`	Yes

Other types

`FormState`

Name	Type	Required
`validation`	`FormValidationState`	Yes
`submission`	`FormSubmissionState`	Yes
`touched`	`boolean`	Yes
`dirty`	`boolean`	Yes
`valid`	`boolean`	Yes
`fields`	`readonly FormFieldState<string>[]`	Yes
`issues`	`readonly FormIssue<string>[]`	Yes
`allIssues`	`readonly FormIssue<string>[]`	Yes

`FormFieldState`

Name	Type	Required
`id`	`string`	Yes
`name`	`string \| null`	Yes
`touched`	`boolean`	Yes
`dirty`	`boolean`	Yes
`valid`	`boolean`	Yes
`issues`	`readonly FormIssue<string>[]`	Yes
`relatedIssues`	`readonly FormIssue<string>[]`	Yes

`FormFieldMetaInput`

Name	Type	Required
`name`	`string \| null \| undefined`	—
`touched`	`boolean \| undefined`	—
`dirty`	`boolean \| undefined`	—

`FormSubscribeOptions`

Name	Type	Required
`equals`	`((previous: Selected, next: Selected) => boolean) \| undefined`	—

`FormSelectorFunction`

type FormSelectorFunction<Selected> = (state: FormState) => Selected

`FormFieldSelectorFunction`

type FormFieldSelectorFunction<Selected> = (field: FormFieldState | null) => Selected

`FormIssue`

Name	Type	Required
`id`	`StableID`	Yes
`message`	`string`	Yes
`source`	`FormIssueSource`	Yes
`fieldId`	`string \| undefined`	—
`relatedFieldIds`	`readonly string[] \| undefined`	—

`FormIssueSource`

type FormIssueSource = 'native' | 'field' | 'form' | 'validate' | 'schema' | 'server'

`FormReinitializeOptions`

Name	Type	Required
`preserve`	`{ readonly touched?: boolean; readonly validation?: boolean; readonly submission?: boolean; } \| undefined`	—

`FormValues`

type FormValues<Shape extends object = Record<string, unknown>> = Readonly<Shape>

`FormSchema`

type FormSchema<Input extends object = Record<string, unknown>, Output extends object = Input> = StandardSchemaV1<FormValues<Input>, FormValues<Output>>

`FormSchemaInput`

type FormSchemaInput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>

`FormSchemaOutput`

type FormSchemaOutput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>

`FormIssueInput`

Name	Type	Required
`id`	`string \| undefined`	—
`message`	`string`	Yes
`path`	`FormFieldPath \| undefined`	—
`relatedPaths`	`readonly FormFieldPath[] \| undefined`	—

`FormSubmitIssue`

type FormSubmitIssue = FormIssueInput

`FormSubmitResult`

type FormSubmitResult =
| void
  | { readonly ok: true }
  | {
      readonly ok: false;
      readonly failure?: FormSubmissionFailure;
      readonly issues?: readonly FormSubmitIssue[];
    }

`FormSubmitHandler`

type FormSubmitHandler<Values extends object = Record<string, unknown>> = (event: FormSubmitEvent<Values>) => FormSubmitResult | PromiseLike<FormSubmitResult>

`FormSubmissionDefinition`

Name	Type	Required
`schema`	`undefined`	—
`onSubmit`	`FormSubmitHandler<Record<string, unknown>>`	Yes

`FormSchemaSubmissionDefinition`

Name	Type	Required
`schema`	`Schema`	Yes
`onSubmit`	`FormSubmitHandler<FormSchemaOutput<Schema>>`	Yes

`FormSubmitErrorMapper`

type FormSubmitErrorMapper =
(
  reason: unknown,
) => FormSubmissionFailure | undefined

`FormResetHandler`

type FormResetHandler = () => void

`FormStateChangeHandler`

type FormStateChangeHandler = (state: FormState) => void

`FormInteractionValidationTrigger`

type FormInteractionValidationTrigger = Exclude<FormValidationTrigger, 'submit'>

`FormValidateContext`

Name	Type	Required
`trigger`	`FormValidationTrigger`	Yes
`intent`	`FormValidationIntent`	Yes
`changedFieldId`	`string \| null`	Yes
`signal`	`AbortSignal`	Yes

`FormValidationIssue`

Name	Type	Required
`message`	`string`	Yes
`path`	`FormFieldPath \| undefined`	—
`relatedPaths`	`readonly FormFieldPath[] \| undefined`	—

`FormValidationResult`

Name	Type	Required
`issues`	`readonly FormValidationIssue[] \| undefined`	—

`FormValidateHandler`

type FormValidateHandler<Values extends object = Record<string, unknown>> =
(
  values: FormValues<Values>,
  context: FormValidateContext,
) => FormValidationResult | PromiseLike<FormValidationResult>

`FormSubmitStartedAction`

type FormSubmitStartedAction = () => number | null

`FormSubmitSucceededAction`

type FormSubmitSucceededAction = (generation: number) => boolean

`FormSubmitFailedAction`

type FormSubmitFailedAction =
(
  generation: number,
  result: {
    readonly failure?: FormSubmissionFailure;
    readonly issues?: readonly FormIssue[];
  },
) => boolean

`FormReplaceIssuesAction`

type FormReplaceIssuesAction =
(
  source: FormIssueSource,
  issues: readonly FormIssue[],
) => boolean

`FormResetAction`

type FormResetAction = () => void

`FormReinitializeAction`

type FormReinitializeAction = (options?: FormReinitializeOptions) => void

`FormRootComponent`

interface FormRootComponent {
  new <Input extends object = Record<string, unknown>, Output extends object = Input>(props: FormRootPublicProps<Input, Output>): {
    $props: FormRootPublicProps<Input, Output>;
    $slots: {
      default?: (props: FormRootSlotProps) => VNodeChild;
    };
    submitStarted: FormSubmitStartedAction;
    submitSucceeded: FormSubmitSucceededAction;
    submitFailed: FormSubmitFailedAction;
    replaceIssues: FormReplaceIssuesAction;
    reinitialize: FormReinitializeAction;
    reset: FormResetAction;
  };
}

`FormFieldController`

Name	Type	Required
`state`	`Readonly<ShallowRef<FormFieldState \| null>>`	Yes
`setMeta`	`(meta: FormFieldMetaInput) => boolean`	Yes
`replaceIssues`	`(source: FormIssueSource, issues: readonly FormIssue[]) => boolean`	Yes
`upsertIssue`	`(issue: FormIssue) => boolean`	Yes
`removeIssue`	`(issueId: string \| number) => boolean`	Yes
`clearIssues`	`(source?: FormIssueSource) => boolean`	Yes

`FormSelectorComponent`

interface FormSelectorComponent {
  new <Selected>(props: FormSelectorProps<Selected>): {
    $props: FormSelectorProps<Selected>;
    $slots: { default?: (props: { readonly selected: Selected }) => VNodeChild };
  };
}

`FormFieldSelectorComponent`

interface FormFieldSelectorComponent {
  new <Selected>(props: FormFieldSelectorProps<Selected>): {
    $props: FormFieldSelectorProps<Selected>;
    $slots: { default?: (props: { readonly selected: Selected }) => VNodeChild };
  };
}

`FormControlCapabilities`

Name	Type	Required
`id`	`boolean \| undefined`	—
`describedBy`	`boolean \| undefined`	—
`invalid`	`boolean \| undefined`	—
`labelledBy`	`boolean \| undefined`	—
`required`	`boolean \| undefined`	—
`disabled`	`boolean \| undefined`	—
`readonly`	`boolean \| undefined`	—

`FormControlParticipation`

Name	Type	Required
`participating`	`boolean`	Yes
`controlProps`	`ComputedRef<Readonly<Record<string, unknown>>>`	Yes

`FormControlRegistration`

Name	Type	Required
`element`	`FormElementSource<HTMLElement>`	Yes
`semanticControl`	`FormElementSource<HTMLElement> \| undefined`	—
`focusTarget`	`FormElementSource<HTMLElement> \| undefined`	—
`validationTarget`	`FormElementSource<HTMLElement> \| undefined`	—
`submissions`	`FormSubmissionSource \| undefined`	—
`labelMode`	`FormLabelMode \| undefined`	—
`capabilities`	`FormControlCapabilities \| undefined`	—
`explicit`	`readonly FormMetadataAttribute[] \| undefined`	—
`reset`	`(() => void) \| undefined`	—
`getValue`	`(() => unknown) \| undefined`	—
`isValueEqual`	`((current: unknown, baseline: unknown) => boolean) \| undefined`	—

`FormElementSource`

type FormElementSource<ElementType extends HTMLElement = HTMLElement> =
| Readonly<ShallowRef<ElementType | null | undefined>>
  | (() => ElementType | null)

`FormLabelMode`

type FormLabelMode = 'for' | 'labelledby' | 'legend'

`FormMetadataAttribute`

type FormMetadataAttribute =
| 'id'
  | 'name'
  | 'form'
  | 'required'
  | 'disabled'
  | 'readonly'
  | 'aria-describedby'
  | 'aria-errormessage'
  | 'aria-invalid'
  | 'aria-labelledby'
  | 'aria-disabled'
  | 'aria-required'
  | 'aria-readonly'

`FormSubmissionCapabilities`

Name	Type	Required
`name`	`boolean \| undefined`	—
`form`	`boolean \| undefined`	—
`required`	`boolean \| undefined`	—
`disabled`	`boolean \| undefined`	—
`readonly`	`boolean \| undefined`	—

`FormSubmissionRegistration`

Name	Type	Required
`element`	`FormElementSource<FormControlSubmissionElement>`	Yes
`relativeName`	`FormControlRelativePath \| undefined`	—
`capabilities`	`FormSubmissionCapabilities \| undefined`	—
`explicit`	`readonly FormMetadataAttribute[] \| undefined`	—

`FormSubmissionSource`

type FormSubmissionSource =
| readonly FormSubmissionRegistration[]
  | (() => readonly FormSubmissionRegistration[])

Vue Form API ​

API ​

Functions ​

defineFormSubmission ​

useFormSelector ​

useFormFieldSelector ​

useFormFieldController ​

provideFormControlOwner ​

useCompositeFormControl ​

useFormControl ​

useNativeInputFormControl ​

Props ​

FormRootProps ​

FormFieldProps ​

FormSelectorProps ​

FormFieldSelectorProps ​

FormPartProps ​

Slots ​

FormRootSlotProps ​

FormFieldSlotProps ​

FormSummarySlotProps ​

FormSubmitSlotProps ​

Events ​

FormSubmitEvent ​

Other types ​

FormState ​

FormFieldState ​

FormFieldMetaInput ​

FormSubscribeOptions ​

FormSelectorFunction ​

FormFieldSelectorFunction ​

FormIssue ​

FormIssueSource ​

FormReinitializeOptions ​

FormValues ​

FormSchema ​

FormSchemaInput ​

FormSchemaOutput ​

FormIssueInput ​

FormSubmitIssue ​

FormSubmitResult ​

FormSubmitHandler ​

FormSubmissionDefinition ​

FormSchemaSubmissionDefinition ​

FormSubmitErrorMapper ​

FormResetHandler ​

FormStateChangeHandler ​

FormInteractionValidationTrigger ​

FormValidateContext ​

FormValidationIssue ​

FormValidationResult ​

FormValidateHandler ​

FormSubmitStartedAction ​

FormSubmitSucceededAction ​

FormSubmitFailedAction ​

FormReplaceIssuesAction ​

FormResetAction ​

FormReinitializeAction ​

FormRootComponent ​

FormFieldController ​

FormSelectorComponent ​

FormFieldSelectorComponent ​

FormControlCapabilities ​

FormControlParticipation ​

FormControlRegistration ​

FormElementSource ​

FormLabelMode ​

FormMetadataAttribute ​

FormSubmissionCapabilities ​

FormSubmissionRegistration ​

FormSubmissionSource ​

Vue Form API

API

Functions

`defineFormSubmission`

`useFormSelector`

`useFormFieldSelector`

`useFormFieldController`

`provideFormControlOwner`

`useCompositeFormControl`

`useFormControl`

`useNativeInputFormControl`

Props

`FormRootProps`

`FormFieldProps`

`FormSelectorProps`

`FormFieldSelectorProps`

`FormPartProps`

Slots

`FormRootSlotProps`

`FormFieldSlotProps`

`FormSummarySlotProps`

`FormSubmitSlotProps`

Events

`FormSubmitEvent`

Other types

`FormState`

`FormFieldState`

`FormFieldMetaInput`

`FormSubscribeOptions`

`FormSelectorFunction`

`FormFieldSelectorFunction`

`FormIssue`

`FormIssueSource`

`FormReinitializeOptions`

`FormValues`

`FormSchema`

`FormSchemaInput`

`FormSchemaOutput`

`FormIssueInput`

`FormSubmitIssue`

`FormSubmitResult`

`FormSubmitHandler`

`FormSubmissionDefinition`

`FormSchemaSubmissionDefinition`

`FormSubmitErrorMapper`

`FormResetHandler`

`FormStateChangeHandler`

`FormInteractionValidationTrigger`

`FormValidateContext`

`FormValidationIssue`

`FormValidationResult`

`FormValidateHandler`

`FormSubmitStartedAction`

`FormSubmitSucceededAction`

`FormSubmitFailedAction`

`FormReplaceIssuesAction`

`FormResetAction`

`FormReinitializeAction`

`FormRootComponent`

`FormFieldController`

`FormSelectorComponent`

`FormFieldSelectorComponent`

`FormControlCapabilities`

`FormControlParticipation`

`FormControlRegistration`

`FormElementSource`

`FormLabelMode`

`FormMetadataAttribute`

`FormSubmissionCapabilities`

`FormSubmissionRegistration`

`FormSubmissionSource`