Form Field

Form Field exposes the elements around form inputs, and an API to compose them.

Import#

import { FormField } from '@volue/wave-react';

// you may also access Form Field's context via hooks:
// import { useFormFieldContext, useFormField } from '@volue/wave-react';

Form Field is a compound component that consists of multiple parts:

FormField: The wrapper that provides context and functionality for all children.
FormField.Label: The label of a form section. The usage is similar to html label.
FormField.HelperText: The message that assists the user in completing the form field that requires additional context.
FormField.FeedbackMessage: The validation feedback message that shows up when the field is flagged during validation.

Examples#

Basic#

It's encouraged to use FormField alongside all standalone form components like TextInput, as every input must have a corresponding label to be accessible to assistive technology.

Labeling#

Make sure that each text field is accompanied by a FormField.Label. Effective form labeling helps users understand what information to enter into a text input.

FormField automatically connects the label, help text, and validation message to the input element for assistive technology using context, so you don't need to provide additional props such as id and htmlFor.

There may be occasions where the label is apparent through context to sighted users, so you wish to omit it from the view. We still need a label attached to the input for assistive technology, in these cases you can provide the .is-hiddenVisually className:

Helper text#

Offer helper text to give the user further instructional content.

Helper text can be used to address concerns that users may have. For example, an e-mail input can provide a hint to clarify usage of the e-mail:

Contextual tooltip#

An info button with contextual help Tooltip or Popover may be placed next to field's label to provide additional information.

Making a field disabled#

By passing the isDisabled prop, the input has disabled set to true.

Making a field required#

By passing the isRequired prop, the input has aria-required set to true, and the FormField.Label will show a red asterisk.

Validation status#

FormField provides interface for showing a feedback message based on the validationStatus. FormField.FeedbackMessage will only show up when the validationStatus is provided. Keep FormField.FeedbackMessage concise and simple.

FormField.FeedbackMessage is automatically associated with the input for assistive technology.

Interactive validation#

Provide clear and useful error messages that help the user fix the issue. Error messages should be displayed in a timely manner — typically when the form is submitted or once the field loses focus (on blur).

Validating a form field when the user leaves the current field can be helpful, but it can also be potentially frustrating to users who tab through controls to navigate a page. Prefer validating field on form submission whenever it makes sense.

Error messages should be removed as early as possible, ideally as the user is typing, so that the user can see when an error has been addressed.

Field elements layout#

You can render <FormField> as one of the layout component, for example Flex. Then you can pass any props Flex supports, for example to specify flow direction. This gives you full control over field's layout.

Sizes#

FormField comes with two sizes ‐ medium and small, with the medium size used by default. Size is propagated to all FormField parts such as FormField.Label or FormField.HelperText.

The size of the FormField is also inherited by all basic form elements like TextInput, TextArea, Checkbox, Radio and Select.

Multi-sizing#

Wave provides applySizes utility, which lets you specify size "scopes" within your app. All FormFields within a scope will share the same size unless overwritten on a per-control basis.

With checkbox or radio groups#

When providing a top-level label for a group of inputs where each individual input already has a label, such as a radio or checkbox button group, overwrite the as prop of the FormField.Label to span.

Under the hood, FormField.Label will be configured to label the group via aria-labelledby.

Accessibility features#

FormField.FormLabel will have htmlFor that points to the id of the form input.
FormField.FeedbackMessage adds aria-describedby and aria-invalid pointing to the form input.
FormField.HelperText adds/extends aria-describedby pointing to the form input.

API Reference#

FormField#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value
`isRequired`	`boolean`	`false`
`isDisabled`	`boolean`	`false`
`isReadOnly`	`boolean`	`false`
`validationStatus`	`enum`	No default value
`size`	`enum`	No default value
`id`	`string`	No default value

FormField.Label#

In addition to the props below, you can pass Text props.

Prop	Type	Default
`as`	`enum`	`label`
`css`	`StitchesCss`	No default value
`requiredIndicator`	`React.ReactElement`	No default value

FormField.RequiredIndicator#

Prop	Type	Default
`css`	`StitchesCss`	No default value

FormField.HelperText#

In addition to the props below, you can pass Text props.

Prop	Type	Default
`css`	`StitchesCss`	No default value

FormField.FeedbackMessage#

In addition to the props below, you can pass Text props.

Prop	Type	Default
`css`	`StitchesCss`	No default value

FormField.FeedbackIcon#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value
`iconName`	`IconToken`	No default value
`size`	`enum`	`"small"`
`pathData`	`string \| string[]`	No default value
`svgSize`	`number`	No default value
`strokeWidth`	`number`	No default value