Field

A component that provides labeling and validation for form controls.

Name

Visible on your profile

<script lang="ts">
	import { Field } from '@sveltery/base/field';
</script>

<Field.Root class="flex w-full max-w-64 flex-col items-start gap-1">
	<Field.Label class="text-sm font-bold text-neutral-950 dark:text-white">Name</Field.Label>
	<Field.Control
		required
		placeholder="Required"
		class="h-8 self-stretch border border-neutral-950 bg-white dark:bg-neutral-950 px-2 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 placeholder:text-neutral-500 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white dark:border-white dark:text-white dark:placeholder:text-neutral-400"
	/>
	<Field.Error class="text-sm text-red-700 dark:text-red-400" match="valueMissing">
		Please enter your name
	</Field.Error>

	<Field.Description class="text-sm text-neutral-600 dark:text-neutral-400">
		Visible on your profile
	</Field.Description>
</Field.Root>

Anatomy

Import the component and assemble its parts:

<script lang="ts">
	import { Field } from '@sveltery/base/field';
</script>

<Field.Root>
	<Field.Label />
	<Field.Control />
	<Field.Description />
	<Field.Item />
	<Field.Error />
	<Field.Validity />
</Field.Root>

API reference

Root

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

disabled boolean | null false

Name: disabled
Description: Whether the component should ignore user interaction. Takes precedence over disabled on <Field.Control>.
Type: boolean | null
Default: false

name string | null —

Name: name
Description: Identifies the field when a form is submitted. Takes precedence over the control's name. Inside a Form with a form source, the name resolves to that source's field, unchecked.
Type: string | null

validate FieldValidate —

Name: validate
Description: Custom validation. Return a message or messages when the value is invalid. An empty result is valid. Asynchronous functions do not block form submission.
Type: FieldValidate

validationMode FormValidationMode 'onSubmit'

Name: validationMode
Description: When the field validates. Takes precedence over <Form validationMode>.
Type: FormValidationMode
Default: 'onSubmit'

validationDebounceTime number 0

Name: validationDebounceTime
Description: How long to wait between validate callbacks when validationMode is onChange.
Type: number
Default: 0

invalid boolean —

Name: invalid
Description: Whether the field is invalid. Useful when an external library owns the state.
Type: boolean

dirty boolean —

Name: dirty
Description: Whether the value has changed from its initial value.
Type: boolean

touched boolean —

Name: touched
Description: Whether the field has been touched.
Type: boolean

field F —

Name: field
Description: A field of the Form's source, such as remote.fields.email. The Field shows its issues, and Field.Control takes its encoded name and value.
Type: F

type ControlType<F> —

Name: type
Type: ControlType<F>

render Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldRootState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <div>. Spread props onto the host element.
Type: Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldRootState, children: Snippet | undefined]>

disabled boolean

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean

touched boolean

Name: touched
Description: Whether the field has been touched.
Type: boolean

dirty boolean

Name: dirty
Description: Whether the field value has changed from its initial value.
Type: boolean

valid boolean | null

Name: valid
Description: Whether the field is valid. null means validity is not known yet.
Type: boolean | null

filled boolean

Name: filled
Description: Whether the field has a value.
Type: boolean

focused boolean

Name: focused
Description: Whether the field is focused.
Type: boolean

data-disabled

Present when the field is disabled.

data-valid

Present when the field is valid.

data-invalid

Present when the field is invalid.

data-dirty

Present when the field's value has changed.

data-touched

Present when the field has been touched.

data-filled

Present when the field is filled.

data-focused

Present when the field control is focused.

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

Label

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

nativeLabel boolean true

Name: nativeLabel
Description: Whether the rendered element is a native <label>. Set false when render produces a different element.
Type: boolean
Default: true

render Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldLabelState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <label>. Spread props onto the host element.
Type: Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldLabelState, children: Snippet | undefined]>

disabled boolean

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean

touched boolean

Name: touched
Description: Whether the field has been touched.
Type: boolean

dirty boolean

Name: dirty
Description: Whether the field value has changed from its initial value.
Type: boolean

valid boolean | null

Name: valid
Description: Whether the field is valid. null means validity is not known yet.
Type: boolean | null

filled boolean

Name: filled
Description: Whether the field has a value.
Type: boolean

focused boolean

Name: focused
Description: Whether the field is focused.
Type: boolean

data-disabled

Present when the field is disabled.

data-valid

Present when the field is in a valid state.

data-invalid

Present when the field is in an invalid state.

data-dirty

Present when the field's value has changed.

data-touched

Present when the field has been touched.

data-filled

Present when the field is filled.

data-focused

Present when the field control is focused.

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

Control

The form control to label and validate. Renders an <input> element.

value string | number | null —

Name: value
Description: Current value. Use bind:value to share it with the parent.
Type: string | number | null
Binding: bind:value

defaultValue string | number | null —

Name: defaultValue
Description: The value an empty value starts from, as on an HTML input.
Type: string | number | null

onValueChange function —

Name: onValueChange
Description: Called when the user edits the control. eventDetails.cancel() vetoes the change.
Type: (value: string, eventDetails: FieldControlChangeEventDetails) => void

render Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldControlState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <input>. Spread props onto the host element.
Type: Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldControlState, children: Snippet | undefined]>

disabled boolean

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean

touched boolean

Name: touched
Description: Whether the field has been touched.
Type: boolean

dirty boolean

Name: dirty
Description: Whether the field value has changed from its initial value.
Type: boolean

valid boolean | null

Name: valid
Description: Whether the field is valid. null means validity is not known yet.
Type: boolean | null

filled boolean

Name: filled
Description: Whether the field has a value.
Type: boolean

focused boolean

Name: focused
Description: Whether the field is focused.
Type: boolean

data-disabled

Present when the field is disabled.

data-valid

Present when the field is in a valid state.

data-invalid

Present when the field is in an invalid state.

data-dirty

Present when the field's value has changed.

data-touched

Present when the field has been touched.

data-filled

Present when the field is filled.

data-focused

Present when the field control is focused.

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

Description

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

render Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldDescriptionState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <p>. Spread props onto the host element.
Type: Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldDescriptionState, children: Snippet | undefined]>

disabled boolean

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean

touched boolean

Name: touched
Description: Whether the field has been touched.
Type: boolean

dirty boolean

Name: dirty
Description: Whether the field value has changed from its initial value.
Type: boolean

valid boolean | null

Name: valid
Description: Whether the field is valid. null means validity is not known yet.
Type: boolean | null

filled boolean

Name: filled
Description: Whether the field has a value.
Type: boolean

focused boolean

Name: focused
Description: Whether the field is focused.
Type: boolean

data-disabled

Present when the field is disabled.

data-valid

Present when the field is in a valid state.

data-invalid

Present when the field is in an invalid state.

data-dirty

Present when the field's value has changed.

data-touched

Present when the field has been touched.

data-filled

Present when the field is filled.

data-focused

Present when the field control is focused.

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

Item

Groups an individual item with its own label and description. Renders a <div> element.

disabled boolean | null false

Name: disabled
Description: Whether the wrapped control should ignore user interaction. <Field.Root disabled> takes precedence.
Type: boolean | null
Default: false

render Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldItemState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <div>. Spread props onto the host element.
Type: Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldItemState, children: Snippet | undefined]>

disabled boolean

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean

touched boolean

Name: touched
Description: Whether the field has been touched.
Type: boolean

dirty boolean

Name: dirty
Description: Whether the field value has changed from its initial value.
Type: boolean

valid boolean | null

Name: valid
Description: Whether the field is valid. null means validity is not known yet.
Type: boolean | null

filled boolean

Name: filled
Description: Whether the field has a value.
Type: boolean

focused boolean

Name: focused
Description: Whether the field is focused.
Type: boolean

data-disabled

Present when the field is disabled.

data-valid

Present when the field is in a valid state.

data-invalid

Present when the field is in an invalid state.

data-dirty

Present when the field's value has changed.

data-touched

Present when the field has been touched.

data-filled

Present when the field is filled.

data-focused

Present when the field control is focused.

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

Error

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

match boolean | keyof ValidityState —

Name: match
Description: Which validity flag shows this message. true always shows it. A string matches that ValidityState flag. Omit it, or pass false, to show form and client errors.
Type: boolean | keyof ValidityState

render Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldErrorState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <div>. Spread props onto the host element.
Type: Snippet<[props: HTMLAttributes<HTMLElement>, state: FieldErrorState, children: Snippet | undefined]>

transitionStatus FieldTransitionStatus

Name: transitionStatus
Description: The transition status of the error message.
Type: FieldTransitionStatus

disabled boolean

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean

touched boolean

Name: touched
Description: Whether the field has been touched.
Type: boolean

dirty boolean

Name: dirty
Description: Whether the field value has changed from its initial value.
Type: boolean

valid boolean | null

Name: valid
Description: Whether the field is valid. null means validity is not known yet.
Type: boolean | null

filled boolean

Name: filled
Description: Whether the field has a value.
Type: boolean

focused boolean

Name: focused
Description: Whether the field is focused.
Type: boolean

data-disabled

Present when the field is disabled.

data-valid

Present when the field is in a valid state.

data-invalid

Present when the field is in an invalid state.

data-dirty

Present when the field's value has changed.

data-touched

Present when the field has been touched.

data-filled

Present when the field is filled.

data-focused

Present when the field control is focused.

data-starting-style

Present when the error message begins animating in.

data-ending-style

Present when the error message is animating out.

Attribute	Description	-
`data-disabled`	Present when the field is disabled.
`data-valid`	Present when the field is in a valid state.
`data-invalid`	Present when the field is in an invalid state.
`data-dirty`	Present when the field's value has changed.
`data-touched`	Present when the field has been touched.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.
`data-starting-style`	Present when the error message begins animating in.
`data-ending-style`	Present when the error message is animating out.

Validity

Renders a custom message from the field's validity.

children Snippet<[state: FieldValidityState]> —

Name: children
Description: Receives the field validity state.
Type: Snippet<[state: FieldValidityState]>

validity

{ badInput: boolean; customError: boolean; patternMismatch: boolean; rangeOverflow: boolean; rangeUnderflow: boolean; stepMismatch: boolean; tooLong: boolean; tooShort: boolean; typeMismatch: boolean; valueMissing: boolean; valid: boolean | null; }

Name: validity
Description: The validity state.
Type: { badInput: boolean; customError: boolean; patternMismatch: boolean; rangeOverflow: boolean; rangeUnderflow: boolean; stepMismatch: boolean; tooLong: boolean; tooShort: boolean; typeMismatch: boolean; valueMissing: boolean; valid: boolean | null; }

transitionStatus FieldTransitionStatus

Name: transitionStatus
Description: The transition status of the invalid state.
Type: FieldTransitionStatus

value unknown

Name: value
Type: unknown

error string

Name: error
Type: string

errors string[]

Name: errors
Type: string[]

initialValue unknown

Name: initialValue
Type: unknown