createInput

Shared form field primitive with validation state, ARIA ID generation, and automatic form registration.

Copy Markdown

Preview Advanced Jun 29, 2026

Usage

import { createInput } from '@vuetify/v0'
import { ref } from 'vue'

const value = ref('')
const input = createInput({
  value,
  rules: [v => !!v || 'Required'],
})

// Field state
input.isDirty.value      // false (no content)
input.isPristine.value   // true (unchanged)
input.isTouched.value    // false (not interacted)

// Trigger validation
await input.validate()
input.isValid.value      // false
input.errors.value       // ['Required']
input.state.value        // 'invalid'

// Update value
value.value = 'hello'
input.isDirty.value      // true
input.isPristine.value   // false

// Reset
input.reset()
value.value              // '' (initial value)
input.isPristine.value   // true
input.isValid.value      // null (unvalidated)

Architecture

Generic Types

createInput is generic over the value type:

// String (default) — for text inputs
createInput({ value: ref('') })

// Number | null — for numeric inputs
createInput<number | null>({
  value: ref<number | null>(null),
  dirty: v => v !== null,
  equals: (a, b) => Object.is(a, b),
})

// ID | ID[] — for select inputs
createInput<ID | ID[]>({
  value: ref<ID[]>([]),
  dirty: v => Array.isArray(v) ? v.length > 0 : v != null,
})

Reactivity

Property	Type	Description
`value`	`Ref<T>`	The field value (same ref passed in)
`isDirty`	`Readonly<Ref<boolean>>`	Has content (via `dirty` predicate)
`isPristine`	`Readonly<Ref<boolean>>`	Unchanged since mount/reset
`isFocused`	`ShallowRef<boolean>`	Writable — component sets on focus/blur
`isTouched`	`ShallowRef<boolean>`	Writable — component sets after first interaction
`isDisabled`	`Readonly<Ref<boolean>>`	Resolved from `disabled` option
`isReadonly`	`Readonly<Ref<boolean>>`	Resolved from `readonly` option
`errors`	`Readonly<Ref<string[]>>`	Merged validation + manual errors
`isValid`	`Readonly<Ref<boolean \| null>>`	Tri-state: null (unvalidated), true, false
`isValidating`	`Readonly<Ref<boolean>>`	Async validation in progress
`state`	`Readonly<Ref<InputState>>`	`'pristine' \| 'valid' \| 'invalid'`

Method	Description
`validate()`	Run rules, returns `Promise<boolean>`
`reset()`	Restore initial value, clear validation

Tip

isDirty and isPristine are not inverses. A pre-filled form field is dirty AND pristine. A cleared field is not-dirty AND not-pristine.

A reusable TextField component built on createInput, then dropped into a profile form twice. Each instance calls createInput in its own setup, so the two fields track validation, dirty, pristine, touched, and focused state completely independently — the composable carries no shared module state. createInput deliberately binds no DOM events, so TextField wires onFocus and onBlur itself: focus flips isFocused, blur sets isTouched and calls validate(). That keeps the “when do I validate” policy in the component where it belongs.

The reusable field also wires the accessibility surface createInput hands it: aria-describedby points at input.errorId while there are errors and falls back to input.descriptionId for the hint, and aria-invalid mirrors isValid === false. Both IDs are generated once and stable across re-renders. The compact flag row underneath makes the field-state model concrete — note that dirty and pristine are independent, so a pre-filled field reads as both at once while a cleared field reads as neither. TextField exposes validate, reset, and isValid via defineExpose, which lets the entry coordinate the whole form: submit validates every field through its template ref before saving, and reset restores each field’s initial value and clears its validation.

Reach for this pattern when you want full control over a field’s markup and styling but do not want to re-implement validation, state tracking, and ARIA wiring by hand. If you only need rule evaluation without the field-state layer, use createValidation directly; if the value is numeric, createNumberField adds Intl formatting and min/max/step on top; and if you would rather not build the shell at all, the Input component packages this exact composable into a ready-made compound surface.

File	Role
`useProfile.ts`	Owns the demo state (name, email, saved) and the per-field validation rules
`TextField.vue`	Reusable field built on createInput — wires focus/blur, ARIA, and reset
`profile-form.vue`	Entry that renders two fields and coordinates submit/reset via template refs