Loading...
Skip to main content

Validation

Provide valuable, actionable feedback to your users with HTML5 form validation, via browser default behaviors or custom styles and JavaScript.

How it works

The form wrappers support native client-side validation and component-based feedback:

  • Client-side validation uses CSS pseudo-classes scoped behind the data-bs-validate attribute. Pass it to ValidationForm to opt in to :user-invalid styling—validation styles only appear after the user interacts with a control (e.g., typing and blurring, or attempting to submit), so required fields don’t show up as invalid on page load.
  • By default, client-side validation only shows invalid styling. To also show success styling for valid fields, set data-bs-validate="valid" on ValidationForm.
  • Server-side validation uses the validation prop on form controls to indicate field state without requiring user interaction.
  • All modern browsers support the constraint validation API, a series of JavaScript methods for validating form controls.
  • Feedback messages may utilize the browser defaults (different for each browser, and unstylable via CSS) or our custom feedback styles with additional HTML and CSS.
  • You may provide custom validity messages with setCustomValidity in JavaScript.

With that in mind, consider the following demos for our custom form validation styles, optional server-side classes, and browser defaults.

Custom styles

For custom validation messages, pass data-bs-validate and noValidate to ValidationForm. The first opts in to :user-invalid styling, while the second disables browser-default feedback tooltips. Custom feedback styles apply colors, borders, and focus styles to better communicate field state.

Set data-bs-validate="valid" to also show success styling on valid fields. Add required to each control and use FormFeedback for field-specific messages. Set its type prop to valid for success feedback.

For accessibility, add aria-describedby to each form control, pointing to the id of its feedback message. This ensures screen readers announce the error when the user focuses an invalid field. The ValidationForm example below also sets aria-invalid on each control at submit time and clears it as users correct their input.

For example, try to submit the form below; our ValidationForm wrapper will intercept submission and relay feedback to you.

Full name is required
$
Please enter a donation amount
Please enter a mailing address
Please provide a city
Please select a state
Required
Arrives in 5-7 business days.
Arrives in 2-3 business days.
<ValidationForm
className="grid grid-cols-1 gap-5"
data-bs-validate=""
noValidate
>
<div className="grid gap-5">
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationCustom01">
Name
</FormLabel>
<FormControl
aria-describedby="validationCustom01Feedback"
defaultValue="Mark Otto"
id="validationCustom01"
required
type="text"
/>
<FormFeedback id="validationCustom01Feedback">
Full name is required
</FormFeedback>
</FormField>
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationCustomUsername">
Donation amount
</FormLabel>
<InputGroup>
<InputGroupText id="inputGroupPrepend">
$
</InputGroupText>
<FormControl
aria-describedby="inputGroupPrepend validationCustomUsernameFeedback"
defaultValue="100"
id="validationCustomUsername"
required
type="number"
/>
</InputGroup>
<FormFeedback id="validationCustomUsernameFeedback">
Please enter a donation amount
</FormFeedback>
</FormField>
</div>
<FormField>
<FormLabel htmlFor="validationCustomAddress">
Address
</FormLabel>
<FormControl
aria-describedby="validationCustomAddressFeedback"
defaultValue="1234 Main St"
id="validationCustomAddress"
required
type="text"
/>
<FormFeedback id="validationCustomAddressFeedback">
Please enter a mailing address
</FormFeedback>
</FormField>
<div className="grid gap-5">
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationCustom03">
City
</FormLabel>
<FormControl
aria-describedby="validationCustom03Feedback"
id="validationCustom03"
required
type="text"
/>
<FormFeedback id="validationCustom03Feedback">
Please provide a city
</FormFeedback>
</FormField>
<FormField className="md:g-col-4">
<FormLabel htmlFor="validationCustom04">
State
</FormLabel>
<FormSelect
aria-describedby="validationCustom04Feedback"
defaultValue=""
id="validationCustom04"
required
>
<option
disabled
value=""
>
<p>
Choose…
</p>
</option>
<option>
...
</option>
</FormSelect>
<FormFeedback id="validationCustom04Feedback">
Please select a state
</FormFeedback>
</FormField>
<FormField className="md:g-col-2">
<FormLabel htmlFor="validationCustom05">
Zip
</FormLabel>
<FormControl
aria-describedby="validationCustom05Feedback"
id="validationCustom05"
required
type="text"
/>
<FormFeedback id="validationCustom05Feedback">
Required
</FormFeedback>
</FormField>
</div>
<FormGroup>
<FormLabel>
Shipping method
</FormLabel>
<FormField className="mb-1">
<Radio
id="validationCustomRadio1"
name="shipping"
required
/>
<FormFieldContent>
<FormLabel
htmlFor="validationCustomRadio1"
plain
>
Standard
</FormLabel>
<FormText>
Arrives in 5-7 business days.
</FormText>
</FormFieldContent>
</FormField>
<FormField>
<Radio
id="validationCustomRadio2"
name="shipping"
required
/>
<FormFieldContent>
<FormLabel
htmlFor="validationCustomRadio2"
plain
>
Express
</FormLabel>
<FormText>
Arrives in 2-3 business days.
</FormText>
</FormFieldContent>
</FormField>
</FormGroup>
<FormField>
<FormSwitch id="validationCustomSwitch" />
<FormLabel
htmlFor="validationCustomSwitch"
plain
>
Subscribe to newsletter
</FormLabel>
</FormField>
<Button
className="justify-self-start"
theme="primary"
type="submit"
variant="solid"
>
Submit form
</Button>
</ValidationForm>

ValidationForm wraps the library’s Form with the upstream validation handlers. It also prevents navigation on successful submission so the demo remains on this page. In an application, replace that demo-only prevention with your submission flow.

'use client';

import { Component, InputEvent, SubmitEvent } from 'react';

import { Form, FormProps } from '../../../source/Form';

export class ValidationForm extends Component<FormProps> {
static displayName = 'ValidationForm';

updateValidity = (control: Element) => {
if (
(control instanceof HTMLInputElement ||
control instanceof HTMLSelectElement ||
control instanceof HTMLTextAreaElement) &&
control.willValidate
)
control.setAttribute('aria-invalid', String(!control.validity.valid));
};

handleSubmit = (event: SubmitEvent<HTMLFormElement>) => {
this.props.onSubmit?.(event);

event.preventDefault();

const { currentTarget } = event;

if (!currentTarget.checkValidity()) event.stopPropagation();

[...currentTarget.elements].forEach(this.updateValidity);
};

handleInput = (event: InputEvent<HTMLFormElement>) => {
this.props.onInput?.(event);

const { target } = event;

if (target instanceof Element && target.hasAttribute('aria-invalid'))
this.updateValidity(target);
};

render() {
return <Form {...this.props} onSubmit={this.handleSubmit} onInput={this.handleInput} />;
}
}

Browser defaults

Not interested in custom validation feedback messages or writing JavaScript to change form behaviors? All good, you can use the browser defaults. Try submitting the form below. Depending on your browser and OS, you’ll see a slightly different style of feedback.

While these feedback styles cannot be styled with CSS, you can still customize the feedback text through JavaScript.

$
Arrives in 5-7 business days.
Arrives in 2-3 business days.
<ValidationForm className="grid grid-cols-1 gap-5">
<div className="grid gap-5">
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationDefault01">
Name
</FormLabel>
<FormControl
defaultValue="Mark Otto"
id="validationDefault01"
required
type="text"
/>
</FormField>
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationDefaultDonation">
Donation amount
</FormLabel>
<InputGroup>
<InputGroupText id="inputGroupPrepend2">
$
</InputGroupText>
<FormControl
aria-describedby="inputGroupPrepend2"
defaultValue="100"
id="validationDefaultDonation"
required
type="number"
/>
</InputGroup>
</FormField>
</div>
<FormField>
<FormLabel htmlFor="validationDefaultAddress">
Address
</FormLabel>
<FormControl
defaultValue="1234 Main St"
id="validationDefaultAddress"
required
type="text"
/>
</FormField>
<div className="grid gap-5">
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationDefault03">
City
</FormLabel>
<FormControl
id="validationDefault03"
required
type="text"
/>
</FormField>
<FormField className="md:g-col-4">
<FormLabel htmlFor="validationDefault04">
State
</FormLabel>
<FormSelect
defaultValue=""
id="validationDefault04"
required
>
<option
disabled
value=""
>
<p>
Choose…
</p>
</option>
<option>
...
</option>
</FormSelect>
</FormField>
<FormField className="md:g-col-2">
<FormLabel htmlFor="validationDefault05">
Zip
</FormLabel>
<FormControl
id="validationDefault05"
required
type="text"
/>
</FormField>
</div>
<FormGroup>
<FormLabel>
Shipping method
</FormLabel>
<FormField className="mb-1">
<Radio
id="validationDefaultRadio1"
name="shippingDefault"
required
/>
<FormFieldContent>
<FormLabel
htmlFor="validationDefaultRadio1"
plain
>
Standard
</FormLabel>
<FormText>
Arrives in 5-7 business days.
</FormText>
</FormFieldContent>
</FormField>
<FormField>
<Radio
id="validationDefaultRadio2"
name="shippingDefault"
required
/>
<FormFieldContent>
<FormLabel
htmlFor="validationDefaultRadio2"
plain
>
Express
</FormLabel>
<FormText>
Arrives in 2-3 business days.
</FormText>
</FormFieldContent>
</FormField>
</FormGroup>
<FormField>
<FormSwitch id="validationDefaultSwitch" />
<FormLabel
htmlFor="validationDefaultSwitch"
plain
>
Subscribe to newsletter
</FormLabel>
</FormField>
<Button
className="justify-self-start"
theme="primary"
type="submit"
variant="solid"
>
Submit form
</Button>
</ValidationForm>

Server-side

We recommend using client-side validation, but for server-side validation set each control's validation prop to invalid or valid. Pair it with FormFeedback to display the corresponding message.

For invalid fields, ensure that the invalid feedback/error message is associated with the relevant form field using aria-describedby (noting that this attribute allows more than one id to be referenced, in case the field already points to additional form text).

Looks great!
Full name is required
$
Looks great!
Please enter a donation amount
Looks great!
Please enter a mailing address
Please provide a city
Please select a state
Required
Arrives in 5-7 business days.
Arrives in 2-3 business days.
<ValidationForm className="grid grid-cols-1 gap-5">
<div className="grid gap-5">
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationServer01">
Name
</FormLabel>
<FormControl
aria-describedby="validationServer01Valid validationServer01Invalid"
defaultValue="Mark Otto"
id="validationServer01"
type="text"
validation="valid"
/>
<FormFeedback
id="validationServer01Valid"
type="valid"
>
Looks great!
</FormFeedback>
<FormFeedback id="validationServer01Invalid">
Full name is required
</FormFeedback>
</FormField>
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationServerDonation">
Donation amount
</FormLabel>
<InputGroup>
<InputGroupText id="inputGroupPrepend3">
$
</InputGroupText>
<FormControl
aria-describedby="inputGroupPrepend3 serverDonateFeedbackValid serverDonateFeedbackInvalid"
defaultValue=""
id="validationServerDonation"
type="number"
validation="invalid"
/>
</InputGroup>
<FormFeedback
id="serverDonateFeedbackValid"
type="valid"
>
Looks great!
</FormFeedback>
<FormFeedback id="serverDonateFeedbackInvalid">
Please enter a donation amount
</FormFeedback>
</FormField>
</div>
<FormField>
<FormLabel htmlFor="validationServerAddress">
Address
</FormLabel>
<FormControl
aria-describedby="validationServerAddressValid validationServerAddressInvalid"
defaultValue="1234 Main St"
id="validationServerAddress"
type="text"
validation="valid"
/>
<FormFeedback
id="validationServerAddressValid"
type="valid"
>
Looks great!
</FormFeedback>
<FormFeedback id="validationServerAddressInvalid">
Please enter a mailing address
</FormFeedback>
</FormField>
<div className="grid gap-5">
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationServer03">
City
</FormLabel>
<FormControl
aria-describedby="validationServer03Feedback"
id="validationServer03"
type="text"
validation="invalid"
/>
<FormFeedback id="validationServer03Feedback">
Please provide a city
</FormFeedback>
</FormField>
<FormField className="md:g-col-4">
<FormLabel htmlFor="validationServer04">
State
</FormLabel>
<FormSelect
aria-describedby="validationServer04Feedback"
defaultValue=""
id="validationServer04"
validation="invalid"
>
<option
disabled
value=""
>
<p>
Choose…
</p>
</option>
<option>
...
</option>
</FormSelect>
<FormFeedback id="validationServer04Feedback">
Please select a state
</FormFeedback>
</FormField>
<FormField className="md:g-col-2">
<FormLabel htmlFor="validationServer05">
Zip
</FormLabel>
<FormControl
aria-describedby="validationServer05Feedback"
id="validationServer05"
type="text"
validation="invalid"
/>
<FormFeedback id="validationServer05Feedback">
Required
</FormFeedback>
</FormField>
</div>
<FormGroup>
<FormLabel>
Shipping method
</FormLabel>
<FormField className="mb-1">
<Radio
id="validationServerRadio1"
name="shippingServer"
validation="invalid"
/>
<FormFieldContent>
<FormLabel
htmlFor="validationServerRadio1"
plain
>
Standard
</FormLabel>
<FormText>
Arrives in 5-7 business days.
</FormText>
</FormFieldContent>
</FormField>
<FormField>
<Radio
id="validationServerRadio2"
name="shippingServer"
validation="invalid"
/>
<FormFieldContent>
<FormLabel
htmlFor="validationServerRadio2"
plain
>
Express
</FormLabel>
<FormText>
Arrives in 2-3 business days.
</FormText>
</FormFieldContent>
</FormField>
</FormGroup>
<FormField>
<FormSwitch id="validationServerSwitch" />
<FormLabel
htmlFor="validationServerSwitch"
plain
>
Subscribe to newsletter
</FormLabel>
</FormField>
<Button
className="justify-self-start"
theme="primary"
type="submit"
variant="solid"
>
Submit form
</Button>
</ValidationForm>

Supported elements

Validation styles work with the form wrappers: FormControl, FormTextArea, FormSelect, Checkbox, Radio, FormSwitch, FormRange, FormFloatingLabel, FormAdornment, and ChipInput. Combobox also supports validation props. For input groups, place the group and its feedback inside FormField.

Please enter a message in the textarea.
Example invalid feedback text
More example invalid feedback text
Example invalid switch feedback
Example invalid select feedback
Example invalid form file feedback
Example invalid range feedback
Example invalid floating label feedback
Example invalid adorned input feedback
@
Please choose a username
Example
Please add at least one tag
<Stack gap={5}>
<FormField>
<FormLabel htmlFor="validationTextarea">
Textarea
</FormLabel>
<FormTextArea
aria-describedby="validationTextareaFeedback"
id="validationTextarea"
placeholder="Required example textarea"
required
validation="invalid"
/>
<FormFeedback id="validationTextareaFeedback">
Please enter a message in the textarea.
</FormFeedback>
</FormField>
<FormGroup>
<FormLabel>
Checkbox
</FormLabel>
<FormField>
<Checkbox
aria-describedby="validationFormCheck1Feedback"
id="validationFormCheck1"
required
validation="invalid"
/>
<FormFieldContent>
<FormLabel
htmlFor="validationFormCheck1"
plain
>
Check this checkbox
</FormLabel>
<FormFeedback id="validationFormCheck1Feedback">
Example invalid feedback text
</FormFeedback>
</FormFieldContent>
</FormField>
</FormGroup>
<FormGroup>
<FormLabel>
Radio
</FormLabel>
<FormField>
<Radio
aria-describedby="validationFormRadioFeedback"
id="validationFormCheck2"
name="radio-stacked"
required
validation="invalid"
/>
<FormLabel
htmlFor="validationFormCheck2"
plain
>
Toggle this radio
</FormLabel>
</FormField>
<FormField>
<Radio
aria-describedby="validationFormRadioFeedback"
id="validationFormCheck3"
name="radio-stacked"
required
validation="invalid"
/>
<FormFieldContent>
<FormLabel
htmlFor="validationFormCheck3"
plain
>
Or toggle this other radio
</FormLabel>
<FormFeedback id="validationFormRadioFeedback">
More example invalid feedback text
</FormFeedback>
</FormFieldContent>
</FormField>
</FormGroup>
<FormGroup>
<FormLabel>
Switch
</FormLabel>
<FormField>
<FormSwitch
aria-describedby="validationFormSwitchFeedback"
id="validationFormSwitch"
validation="invalid"
/>
<FormFieldContent>
<FormLabel
htmlFor="validationFormSwitch"
plain
>
Toggle this switch
</FormLabel>
<FormFeedback id="validationFormSwitchFeedback">
Example invalid switch feedback
</FormFeedback>
</FormFieldContent>
</FormField>
</FormGroup>
<FormField>
<FormLabel htmlFor="validationSelect">
Select
</FormLabel>
<FormSelect
aria-describedby="validationSelectFeedback"
id="validationSelect"
required
validation="invalid"
>
<option value="">
Open this select menu
</option>
<option value="1">
One
</option>
<option value="2">
Two
</option>
<option value="3">
Three
</option>
</FormSelect>
<FormFeedback id="validationSelectFeedback">
Example invalid select feedback
</FormFeedback>
</FormField>
<FormField>
<FormLabel htmlFor="validationFile">
File input
</FormLabel>
<FormControl
aria-describedby="validationFileFeedback"
id="validationFile"
required
type="file"
validation="invalid"
/>
<FormFeedback id="validationFileFeedback">
Example invalid form file feedback
</FormFeedback>
</FormField>
<FormField>
<FormLabel htmlFor="validationRange">
Range
</FormLabel>
<FormRange
aria-describedby="validationRangeFeedback"
id="validationRange"
max="5"
min="0"
required
validation="invalid"
/>
<FormFeedback id="validationRangeFeedback">
Example invalid range feedback
</FormFeedback>
</FormField>
<FormField>
<FormFloatingLabel>
<FormLabel
htmlFor="validationFloating"
plain
>
Email address
</FormLabel>
<FormControl
aria-describedby="validationFloatingFeedback"
defaultValue="test@example.com"
id="validationFloating"
placeholder="name@example.com"
type="email"
validation="invalid"
/>
</FormFloatingLabel>
<FormFeedback
className="d-block"
id="validationFloatingFeedback"
>
Example invalid floating label feedback
</FormFeedback>
</FormField>
<FormField>
<FormLabel htmlFor="validationAdorn">
Adorned input
</FormLabel>
<FormAdornment validation="invalid">
<FormAdornmentIcon
aria-hidden="true"
name="file-earmark-code"
/>
<FormGhost
aria-describedby="validationAdornFeedback"
id="validationAdorn"
placeholder="Search..."
type="text"
/>
</FormAdornment>
<FormFeedback id="validationAdornFeedback">
Example invalid adorned input feedback
</FormFeedback>
</FormField>
<FormField>
<FormLabel htmlFor="validationInputGroup">
Input group
</FormLabel>
<InputGroup>
<InputGroupText>
@
</InputGroupText>
<FormControl
aria-describedby="validationInputGroupFeedback"
id="validationInputGroup"
placeholder="Username"
type="text"
validation="invalid"
/>
</InputGroup>
<FormFeedback id="validationInputGroupFeedback">
Please choose a username
</FormFeedback>
</FormField>
<FormField>
<FormLabel htmlFor="validationChipInput">
Tags
</FormLabel>
<ChipInput dismissible={false}>
<Chip>
Example
</Chip>
<FormGhost
aria-describedby="validationChipInputFeedback"
id="validationChipInput"
placeholder="Add tag..."
type="text"
validation="invalid"
/>
</ChipInput>
<FormFeedback id="validationChipInputFeedback">
Please add at least one tag
</FormFeedback>
</FormField>
</Stack>

Tooltips

If your form layout allows it, you can swap the .{valid|invalid}-feedback classes for .{valid|invalid}-tooltip classes to display validation feedback in a styled tooltip. These tooltips build on the base .tooltip styles, so you’ll need to have those included in your compiled CSS as well.

We don’t recommend using tooltips for checkboxes, radios, and switches because their placement is not reliable or consistent in most cases. You can also use a combination of feedback text and tooltips in your forms.

This example functions the same as the custom styles example. Click the submit button to see the validation tooltips.

Full name is required
$
Please enter a donation amount
Please enter a mailing address
Please provide a city
Please select a state
Required
Arrives in 5-7 business days.
Please select a shipping method
Arrives in 2-3 business days.
<ValidationForm
className="grid grid-cols-1 gap-5"
data-bs-validate=""
noValidate
>
<div className="grid gap-5">
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationTooltip01">
Name
</FormLabel>
<FormControl
aria-describedby="validationTooltip01Feedback"
defaultValue="Mark Otto"
id="validationTooltip01"
required
type="text"
/>
<FormFeedback
id="validationTooltip01Feedback"
tooltip
>
Full name is required
</FormFeedback>
</FormField>
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationTooltipDonation">
Donation amount
</FormLabel>
<InputGroup>
<InputGroupText id="inputGroupTooltipPrepend">
$
</InputGroupText>
<FormControl
aria-describedby="inputGroupTooltipPrepend validationTooltipDonationFeedback"
defaultValue="100"
id="validationTooltipDonation"
required
type="number"
/>
</InputGroup>
<FormFeedback
id="validationTooltipDonationFeedback"
tooltip
>
Please enter a donation amount
</FormFeedback>
</FormField>
</div>
<FormField>
<FormLabel htmlFor="validationTooltipAddress">
Address
</FormLabel>
<FormControl
aria-describedby="validationTooltipAddressFeedback"
defaultValue="1234 Main St"
id="validationTooltipAddress"
required
type="text"
/>
<FormFeedback
id="validationTooltipAddressFeedback"
tooltip
>
Please enter a mailing address
</FormFeedback>
</FormField>
<div className="grid gap-5">
<FormField className="md:g-col-6">
<FormLabel htmlFor="validationTooltip03">
City
</FormLabel>
<FormControl
aria-describedby="validationTooltip03Feedback"
id="validationTooltip03"
required
type="text"
/>
<FormFeedback
id="validationTooltip03Feedback"
tooltip
>
Please provide a city
</FormFeedback>
</FormField>
<FormField className="md:g-col-4">
<FormLabel htmlFor="validationTooltip04">
State
</FormLabel>
<FormSelect
aria-describedby="validationTooltip04Feedback"
defaultValue=""
id="validationTooltip04"
required
>
<option
disabled
value=""
>
<p>
Choose…
</p>
</option>
<option>
...
</option>
</FormSelect>
<FormFeedback
id="validationTooltip04Feedback"
tooltip
>
Please select a state
</FormFeedback>
</FormField>
<FormField className="md:g-col-2">
<FormLabel htmlFor="validationTooltip05">
Zip
</FormLabel>
<FormControl
aria-describedby="validationTooltip05Feedback"
id="validationTooltip05"
required
type="text"
/>
<FormFeedback
id="validationTooltip05Feedback"
tooltip
>
Required
</FormFeedback>
</FormField>
</div>
<FormGroup>
<FormLabel>
Shipping method
</FormLabel>
<FormField className="mb-1">
<Radio
id="validationTooltipRadio1"
name="shippingTooltip"
required
/>
<FormFieldContent>
<FormLabel
htmlFor="validationTooltipRadio1"
plain
>
Standard
</FormLabel>
<FormText>
Arrives in 5-7 business days.
</FormText>
<FormFeedback>
Please select a shipping method
</FormFeedback>
</FormFieldContent>
</FormField>
<FormField>
<Radio
id="validationTooltipRadio2"
name="shippingTooltip"
required
/>
<FormFieldContent>
<FormLabel
htmlFor="validationTooltipRadio2"
plain
>
Express
</FormLabel>
<FormText>
Arrives in 2-3 business days.
</FormText>
</FormFieldContent>
</FormField>
</FormGroup>
<FormField>
<FormSwitch id="validationTooltipSwitch" />
<FormLabel
htmlFor="validationTooltipSwitch"
plain
>
Subscribe to newsletter
</FormLabel>
</FormField>
<Button
className="justify-self-start"
theme="primary"
type="submit"
variant="solid"
>
Submit form
</Button>
</ValidationForm>
Documentation navigation
On this page
On this page