Field · base-ui-svelte

We will not share your email.

Validation notes

Controlled Field.Control / Input values sync filled and dirty state when the prop changes (not only on input).
While an async validate is in flight, validity is neutral (valid: null) unless a native constraint already fails, or a prior custom error is kept in onBlur / onChange modes.
Field only clears custom validity messages it owns; foreign setCustomValidity messages are restored when Field’s message is cleared.

API Reference

Props mirror Base UI React where applicable, adapted for Svelte 5. Native HTML attributes for the rendered element are also accepted unless noted.

Field.Root

Groups all parts of the field. Renders a <div> element.

Props

name string —

Name: name
Description: Identifies the field when a form is submitted. Takes precedence over the name prop on the <Field.Control> component.
Type: string | undefined

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

invalid boolean —

Name: invalid
Description: Whether the field is invalid. Useful when the field state is controlled by an external library.
Type: boolean | undefined

validate function —

Name: validate
Description: A function for custom validation. Return a string or an array of strings with the error message(s) if the value is invalid, or null if the value is valid. Asynchronous functions are supported, but they do not prevent form submission when using validationMode="onSubmit".
Type: | ((value: string) => string | string[] | null | Promise<string | string[] | null>) | undefined

validationMode FieldValidationMode 'onSubmit'

Name: validationMode
Description: Determines when the field should be validated. This takes precedence over the validationMode prop on <Form>. onSubmit: triggers validation when the form is submitted, and re-validates on change after submission.onBlur: triggers validation when the control loses focus.onchange: triggers validation on every change to the control value.
Type: FieldValidationMode
Default: 'onSubmit'

validationDebounceTime number 0

Name: validationDebounceTime
Description: Debounce (ms) before running validate on change.
Type: number
Default: 0

dirty boolean —

Name: dirty
Description: Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library.
Type: boolean | undefined

defaultDirty boolean —

Name: defaultDirty
Description: —
Type: boolean

onDirtyChange function —

Name: onDirtyChange
Description: —
Type: ((dirty: boolean) => void) | undefined

touched boolean —

Name: touched
Description: Whether the field has been touched. Useful when the field state is controlled by an external library.
Type: boolean | undefined

defaultTouched boolean —

Name: defaultTouched
Description: —
Type: boolean

onTouchedChange function —

Name: onTouchedChange
Description: —
Type: ((touched: boolean) => void) | undefined

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet< [ { disabled: boolean; touched: boolean; dirty: boolean; focused: boolean; filled: boolean; valid: boolean | null; }, ] >

Data attributes

Attribute	Description
`data-dirty`	Present when the field's value has changed.
`data-disabled`	Present when the field is disabled.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.
`data-invalid`	Present when the field is invalid.
`data-touched`	Present when the field has been touched.
`data-valid`	Present when the field is valid.

The form control to label and validate. Renders an <input> element. You can omit this part and use any Base UI input component instead. For example, [Input](https://base-ui.com/react/components/input), [Checkbox](https://base-ui.com/react/components/checkbox), or [Select](https://base-ui.com/react/components/select), among others, will work with Field out of the box.

Props

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean | undefined
Default: false

value string —

Name: value
Description: Controlled value.
Type: string | undefined

defaultValue string —

Name: defaultValue
Description: Uncontrolled initial value.
Type: string

onValueChange function —

Name: onValueChange
Description: Event handler called when the value changes.
Type: ((value: string, event: Event) => void) | undefined

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-dirty`	Present when the field's value has changed.
`data-disabled`	Present when the field is disabled.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.
`data-invalid`	Present when the field is in an invalid state.
`data-touched`	Present when the field has been touched.
`data-valid`	Present when the field is in a valid state.

Field.Description

A paragraph with additional information about the field. Renders a <p> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-dirty`	Present when the field's value has changed.
`data-disabled`	Present when the field is disabled.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.
`data-invalid`	Present when the field is in an invalid state.
`data-touched`	Present when the field has been touched.
`data-valid`	Present when the field is in a valid state.

Field.Error

An error message displayed if the field control fails validation. Renders a <div> element.

Props

match FieldErrorMatch —

Name: match
Description: When true, always show. When a ValidityState key, show when that flag is true. When omitted, show when the field is invalid (or has a form error).
Type: FieldErrorMatch | undefined

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet<[{ error: string }]>

Data attributes

Attribute	Description
`data-dirty`	Present when the field's value has changed.
`data-disabled`	Present when the field is disabled.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.
`data-invalid`	Present when the field is in an invalid state.
`data-touched`	Present when the field has been touched.
`data-valid`	Present when the field is in a valid state.

Field.Item

Groups individual items in a checkbox group or radio group with a label and description. Renders a <div> element.

Props

render string —

Name: render
Description: HTML element tag to render instead of the default host element.
Type: string

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-dirty`	Present when the field's value has changed.
`data-disabled`	Present when the field is disabled.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.
`data-invalid`	Present when the field is in an invalid state.
`data-touched`	Present when the field has been touched.
`data-valid`	Present when the field is in a valid state.

Field.Label

An accessible label that is automatically associated with the field control. Renders a <label> element.

Props

nativeLabel boolean true

Name: nativeLabel
Description: When false, render a span instead of a native label.
Type: boolean
Default: true

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-dirty`	Present when the field's value has changed.
`data-disabled`	Present when the field is disabled.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.
`data-invalid`	Present when the field is in an invalid state.
`data-touched`	Present when the field has been touched.
`data-valid`	Present when the field is in a valid state.

Field.Validity

Used to display a custom message based on the field's validity. Requires children to be a function that accepts field validity state as an argument.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet<[FieldValidityState]>

Validation notes

API Reference

Field.Root

Field.Control

Field.Description

Field.Error

Field.Item

Field.Label

Field.Validity