Field Errors

Variations Design Guidelines Code Reference Accessibility

Field Errors
updated

HTML/CSS Available
Web Component Beta
Last Updated
2.15.0

Field errors indicate form elements with invalid or missing entries and provide a description of the error.

See Forms for guidance on composing full forms.

Variations Design Guidelines Code Reference Accessibility

Variations

Default

This is example error text.

Default

This is example error text.

HTML

Web Component

<span class="mds-form__field-error" id="error-id" role="alert">
    <span class="mds-form__field-error-text"> This is example error text. </span>
</span>

<mds-field-error id="error-id" visible>This is example error text.</mds-field-error>

Always wrap grouped form elements in a mds-form__field-group container. See the Forms composition section for more guidelines on constructing forms.

<div class="mds-form__field-group">
    <label class="mds-form__label" for="first-name">First Name</label>
    <input class="mds-form__input" type="text" id="first-name" placeholder="First Name" />
    <span class="mds-form__field-error" id="error-id" role="alert">
        <span class="mds-form__field-error-text"> This is example error text. </span>
    </span>
</div>

Sizing

Sizing affects text size. The default size is medium, and you can use modifier classes or props to make the field error smaller or larger.

Small

This is example error text.

Medium (Default)

This is example error text.

Large

This is example error text.

Small

This is example error text.

Medium (Default)

This is example error text.

Large

This is example error text.

HTML

Web Component

<span class="mds-form__field-error mds-form__field-error--small" id="error-id" role="alert">
    <span class="mds-form__field-error-text"> This is example error text. </span>
</span>

<mds-field-error id="error-id" size="small" visible>This is example error text.</mds-field-error>

Examples

Input

HTML

Web Component

<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group mds-form--error">
        <label class="mds-form__label" for="error-first-name"> First Name <abbr class="mds-form__label-required-indicator" title="This field is required." aria-label="This field is required.">*</abbr>
        </label>
        <input class="mds-form__input" type="text" id="error-first-name" aria-describedby="first-name-error" aria-invalid="true">
        <span class="mds-form__field-error" id="first-name-error" role="alert">
            <span class="mds-form__field-error-text"> You must enter your first name. </span>
        </span>
    </div>
</form>

<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group mds-form--error">
        <mds-label id="first-name-label" text="First Name" required for="first-name"></mds-label>
        <mds-input required id="first-name" aria-describedby="error-id" aria-invalid></mds-input>
        <mds-field-error id="error-id" visible>You must enter your first name.</mds-field-error>
    </div>
</form>

Select

Expense Type *

Select an expense type.

Select

HTML

Web Component

<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group mds-form--error">
        <label class="mds-form__label" for="error-select"> Expense Type <abbr class="mds-form__label-required-indicator" title="This field is required." aria-label="This field is required.">*</abbr>
        </label>
        <div class="mds-form__select">
            <select class="mds-form__select-input" id="error-select" aria-invalid="true">
                <option class="mds-form__select-option" value="">Select an Expense Type</option>
                <option class="mds-form__select-option" value="vacation">Vacation</option>
                <option class="mds-form__select-option" value="public_college">Public College</option>
                <option class="mds-form__select-option" value="private_college">Private College</option>
                <option class="mds-form__select-option" value="medical">Medical</option>
            </select>
            <div class="mds-form__select-visual-wrap"></div>
            <span class="mds-form__select-open-indicator">
                <svg class="mds-icon mds-form__select-open-icon" aria-hidden="true">
                    <use xlink:href="/icons/mds.svg#caret-down--s">
                    </use>
                </svg>
            </span>
        </div>
        <span class="mds-form__field-error" role="alert">
            <span class="mds-form__field-error-text"> Select an expense type. </span>
        </span>
    </div>
</form>

<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group mds-form--error">
        <mds-label id="expense-type" text="Expense Type" required for="expense-types"></mds-label>
        <mds-select id="expense-types" aria-invalid aria-describedby="error-id" placeholder="Select an Expense Type" options='[{"text": "Vacation", "value": "vacation"}, {"text": "Public College", "value": "public_college"}, {"text": "Private College", "value": "private_college"}, {"text": "Medical", "value": "medical"}]'></mds-select>
        <mds-field-error id="error-id" visible>Select an expense type.</mds-field-error>
    </div>
</form>

Checkbox Group

Select one or more statistics to view. * Average Minimum Maximum You must select at least one statistic.

Checkbox Group

HTML

Web Component

<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group mds-form--error">
        <fieldset class="mds-form__checkbox-group" role="group">
            <legend class="mds-form__checkbox-group-label"> Select one or more statistics to view. <abbr class="mds-form__label-required-indicator" title="Please select at least one option." aria-label="Please select at least one option.">*</abbr>
            </legend>
            <label class="mds-form__checkbox" for="average--63613">
                <input id="average--63613" type="checkbox" class="mds-form__checkbox-input" aria-describedby="checkbox-error" aria-invalid="true" />
                <span class="mds-form__checkbox-visible-wrap">
                    <span class="mds-form__checkbox-visual">
                        <svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
                            <use xlink:href="/icons/mds.svg#check--s">
                            </use>
                        </svg>
                        <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                            <use xlink:href="/icons/mds.svg#minus--s">
                            </use>
                        </svg>
                    </span>
                    <span class="mds-form__checkbox-text"> Average </span>
                </span>
            </label>
            <label class="mds-form__checkbox" for="minimum--52360">
                <input id="minimum--52360" type="checkbox" class="mds-form__checkbox-input" aria-describedby="checkbox-error" aria-invalid="true" />
                <span class="mds-form__checkbox-visible-wrap">
                    <span class="mds-form__checkbox-visual">
                        <svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
                            <use xlink:href="/icons/mds.svg#check--s">
                            </use>
                        </svg>
                        <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                            <use xlink:href="/icons/mds.svg#minus--s">
                            </use>
                        </svg>
                    </span>
                    <span class="mds-form__checkbox-text"> Minimum </span>
                </span>
            </label>
            <label class="mds-form__checkbox" for="maximum--25585">
                <input id="maximum--25585" type="checkbox" class="mds-form__checkbox-input" aria-describedby="checkbox-error" aria-invalid="true" />
                <span class="mds-form__checkbox-visible-wrap">
                    <span class="mds-form__checkbox-visual">
                        <svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
                            <use xlink:href="/icons/mds.svg#check--s">
                            </use>
                        </svg>
                        <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                            <use xlink:href="/icons/mds.svg#minus--s">
                            </use>
                        </svg>
                    </span>
                    <span class="mds-form__checkbox-text"> Maximum </span>
                </span>
            </label>
            <span class="mds-form__field-error" id="checkbox-error" role="alert">
                <span class="mds-form__field-error-text"> You must select at least one statistic. </span>
            </span>
        </fieldset>
    </div>
</form>

<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group mds-form--error">
        <mds-checkbox-group label="Select one or more statistics to view." required>
            <mds-checkbox aria-invalid aria-describedby="error-id">Average</mds-checkbox>
            <mds-checkbox aria-invalid aria-describedby="error-id">Minimum</mds-checkbox>
            <mds-checkbox aria-invalid aria-describedby="error-id">Maximum</mds-checkbox>
        </mds-checkbox-group>
        <mds-field-error id="error-id" visible>You must select at least one statistic.</mds-field-error>
    </div>
</form>

Use When

Indicating form elements with invalid or missing entries.
Providing guidance on how to resolve an invalid form entry.

Don’t Use When

Providing a user with password requirements or other criteria for filling out a form. Instead, use Microcopy

Visual Language

Match the size of field errors to the form element they’re paired with.

Behaviors

Never account for the space an error message may occupy in your layout. Instead, the error message should push the elements below down to make room.
See the Errors UX pattern for additional behavioral guidelines.

Editorial

Use full sentences with punctuation for error description.
Acknowledge what is keeping a user from proceeding, but don’t make them feel like they did something wrong.
If we’re directly responsible for the error, tell them.
Provide a user at least one way to resolve the problem.
If an error has the potential to repeat, tell a user what they should do, i.e., “If the site continues to not recognize your account, email us at [email protected].”

CSS

Class References

Class	Applies to	Outcome
`mds-form--error`	`mds-form__field-group`	Applies error styles to the form element within the field group.
`mds-form__field-error--small`	`mds-form__field-error`	Applies small styles to the descriptive error text.
`mds-form__field-error--large`	`mds-form__field-error`	Applies large styles to the descriptive error text.

Web Component

Props

Prop	Type	Validation	Default	Description
`class`	String	—	—	A space-separated list of class names that will be appended to the default `mds-form__field-error` class.
`id`	String	Required	—	The `id` attribute for the HTML element.
`visible`	Boolean	—	`false`	Controls visibility of the field error.
`size`	String	Enum: `["small", "medium", "large"]`	`medium`	Alters the size of the field error.
`text`	String	Required	—	The text for the field error. Can also be passed via the default slot.

Slots

Default Slot

Any text or markup passed in between the <mds-field-error></mds-field-error> tags will be used as the field error’s text content. This slot can accept plain text, or a combination of text and any tags where appropriate.

Events

Event Name	Description
`mds-field-error-activated`	Triggers when the `visible` prop is set to `true`.
`mds-field-error-deactivated`	Triggers when the `visible` prop is set to `false`.

Usage Examples

Setting the text and size:

<!-- Using Props -->
<mds-field-error text="Your password must contain a letter and a number." id="error-password" size="small"></mds-field-error>
<!-- Using Slots -->
<mds-field-error id="error-password" size="small"> Your password must contain a letter and a number. </mds-field-error>

Implementation

Always include role="alert" on .mds-form__field-error components.
Include an aria-describedby attribute on each input, textarea, or select that has an .mds-form__field-error component providing additional information. The value of the aria-describedby attribute must match the id attribute on the .mds-form__field-error component.

See the Forms composition section for more information.

Variations

Default

Sizing

Examples

Input

Select

Checkbox Group

Use When

Don’t Use When

Visual Language

Behaviors

Editorial

Related UI Components

Related UX Patterns

CSS

Class References

Web Component

Props

Slots

Default Slot

Events

Usage Examples

Implementation