Form

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import Form, FormErrorFocus, useFormPending from @prepared911/ui/form.

Props

Prop	Type	Default	Notes
`announceFieldErrors`	`boolean`	`true`	Announces a control's error politely once when it appears or changes outside a submit attempt.
`children`	`ReactNode`	none	Fields and actions. Form sets no gap.
`errorSummary`	`LocalizedMessage`	none	Copy for the live summary region; also makes the form invalid.
`invalid`	`boolean`	`errorSummary` is set	Decides whether a failed attempt moves focus. Writes `data-invalid`.
`errorFocus`	`FormErrorFocus`	`FirstInvalid`	Where focus goes after a failed attempt: `FirstInvalid`, `Summary`, or `None`.
`noValidate`	`boolean`	`true`	Native `noValidate`. `false` lets the browser block the submit.
`pending`	`boolean`	tracks the `onSubmit` promise	Sets `aria-busy`, ignores further submits, and feeds `useFormPending`.
`onSubmit`	`(event) => void \| Promise<void>`	none	Runs after native validation, unless a submit is pending.
`onAfterReset`	`(event: Event) => void`	none	Runs after a reset that no handler canceled.
`className`	`string`	none	Appended after generated classes.
`ref`	`Ref<HTMLFormElement>`	none	Host ref.

Native form attributes (action, method, noValidate, autoComplete, aria-*, data-*) pass through, and aria-describedby merges with the generated summary id.

Hook

useFormPending(): boolean reads the enclosing Form's pending state. It returns false outside a Form.

Omissions

No style, role, or tabIndex. Only onReset, onInvalid, onChange, onInput, onFocus, and onBlur are forwarded besides onSubmit. See FormProps TSDoc in props.ts for the full typed surface.

Props

Name	Type	Default	Description
`announceFieldErrors`	`boolean`	`true`	Whether a control's error that appears or changes outside a submit attempt, such as after blur or async validation, is announced politely once through the live announcer. A submit attempt never announces each field: its focus move and `errorSummary` speak the errors. A cleared error announces nothing. Defaults to `true`; pass `false` when the page announces validation itself.
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`children`	`ReactNode`	—	The fields and the submit control. Form draws none of them and sets no gap; stack them with FlexBox.
`className`	`string`	—	Classes appended after the generated classes. Put overrides in `@layer chroma.overrides`.
`errorFocus`	`FormErrorFocus`	`FormErrorFocus.FirstInvalid`	Where focus goes after a submit attempt ends with the form invalid. Defaults to {@link FormErrorFocus.FirstInvalid}. Focus moves once per attempt, not on every render.
`errorSummary`	`LocalizedMessage`	—	Copy for the form-level error summary. When set, a live region (`role="alert"`) renders before the children, is announced when it appears, and is linked to the form through `aria-describedby`. The copy comes from the caller; Form ships no default string.
`invalid`	`boolean`	—	Whether the form is invalid, which decides if a submit attempt moves focus. Defaults to whether `errorSummary` is set. Pass it when per-field errors exist without a summary.
`noValidate`	`boolean`	`true`	Sets the native `noValidate` attribute. Defaults to `true`, so browser constraint validation does not run ahead of the validation the caller runs in `onSubmit`. Pass `false` to let the browser block the submit and focus its first invalid control.
`onAfterReset`	`((event: Event) => void)`	—	Called after the form resets and no `reset` handler canceled it, with the platform event. Use it to clear error state the form does not own. Form clears its own pending focus request.
`onSubmit`	`((event: FormEvent<HTMLFormElement>) => void \| Promise<void>)`	—	Called when the form submits, after native constraint validation passes when `noValidate` is `false`, and unless a submit is already pending. It plays the role of ui-forms' `onValid`: validate here. Call `event.preventDefault()` to replace the native navigation with an explicit action. Return a promise to keep the form pending until it settles. A rejection stays with the caller; Form does not catch it.
`pending`	`boolean`	—	Whether a submit is pending. While pending, the form sets `aria-busy`, ignores further submits, and shares the state with {@link useFormPending }. Omit it to have Form track the promise the `onSubmit` handler returns. The page is never covered or disabled.
`ref`	`Ref<HTMLFormElement>`	—	Ref to the rendered `form`.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

On this page

Form

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import Form, FormErrorFocus, useFormPending from @prepared911/ui/form.

Props

Prop	Type	Default	Notes
`announceFieldErrors`	`boolean`	`true`	Announces a control's error politely once when it appears or changes outside a submit attempt.
`children`	`ReactNode`	none	Fields and actions. Form sets no gap.
`errorSummary`	`LocalizedMessage`	none	Copy for the live summary region; also makes the form invalid.
`invalid`	`boolean`	`errorSummary` is set	Decides whether a failed attempt moves focus. Writes `data-invalid`.
`errorFocus`	`FormErrorFocus`	`FirstInvalid`	Where focus goes after a failed attempt: `FirstInvalid`, `Summary`, or `None`.
`noValidate`	`boolean`	`true`	Native `noValidate`. `false` lets the browser block the submit.
`pending`	`boolean`	tracks the `onSubmit` promise	Sets `aria-busy`, ignores further submits, and feeds `useFormPending`.
`onSubmit`	`(event) => void \| Promise<void>`	none	Runs after native validation, unless a submit is pending.
`onAfterReset`	`(event: Event) => void`	none	Runs after a reset that no handler canceled.
`className`	`string`	none	Appended after generated classes.
`ref`	`Ref<HTMLFormElement>`	none	Host ref.

Native form attributes (action, method, noValidate, autoComplete, aria-*, data-*) pass through, and aria-describedby merges with the generated summary id.

Hook

useFormPending(): boolean reads the enclosing Form's pending state. It returns false outside a Form.

Omissions

Props

Name	Type	Default	Description
`announceFieldErrors`	`boolean`	`true`	Whether a control's error that appears or changes outside a submit attempt, such as after blur or async validation, is announced politely once through the live announcer. A submit attempt never announces each field: its focus move and `errorSummary` speak the errors. A cleared error announces nothing. Defaults to `true`; pass `false` when the page announces validation itself.
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`children`	`ReactNode`	—	The fields and the submit control. Form draws none of them and sets no gap; stack them with FlexBox.
`className`	`string`	—	Classes appended after the generated classes. Put overrides in `@layer chroma.overrides`.
`errorFocus`	`FormErrorFocus`	`FormErrorFocus.FirstInvalid`	Where focus goes after a submit attempt ends with the form invalid. Defaults to {@link FormErrorFocus.FirstInvalid}. Focus moves once per attempt, not on every render.
`errorSummary`	`LocalizedMessage`	—	Copy for the form-level error summary. When set, a live region (`role="alert"`) renders before the children, is announced when it appears, and is linked to the form through `aria-describedby`. The copy comes from the caller; Form ships no default string.
`invalid`	`boolean`	—	Whether the form is invalid, which decides if a submit attempt moves focus. Defaults to whether `errorSummary` is set. Pass it when per-field errors exist without a summary.
`noValidate`	`boolean`	`true`	Sets the native `noValidate` attribute. Defaults to `true`, so browser constraint validation does not run ahead of the validation the caller runs in `onSubmit`. Pass `false` to let the browser block the submit and focus its first invalid control.
`onAfterReset`	`((event: Event) => void)`	—	Called after the form resets and no `reset` handler canceled it, with the platform event. Use it to clear error state the form does not own. Form clears its own pending focus request.
`onSubmit`	`((event: FormEvent<HTMLFormElement>) => void \| Promise<void>)`	—	Called when the form submits, after native constraint validation passes when `noValidate` is `false`, and unless a submit is already pending. It plays the role of ui-forms' `onValid`: validate here. Call `event.preventDefault()` to replace the native navigation with an explicit action. Return a promise to keep the form pending until it settles. A rejection stays with the caller; Form does not catch it.
`pending`	`boolean`	—	Whether a submit is pending. While pending, the form sets `aria-busy`, ignores further submits, and shares the state with {@link useFormPending }. Omit it to have Form track the promise the `onSubmit` handler returns. The page is never covered or disabled.
`ref`	`Ref<HTMLFormElement>`	—	Ref to the rendered `form`.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

On this page