Field Errors
updated

  • HTML/CSS Available
  • Web Component Beta
  • Last Updated

    2.18.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

Default

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

Input
You must enter your first name.
Input
You must enter your first name.
HTML Web Component
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group mds-form__field-group--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__field-group--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

Select
Select an expense type.
Select
Select an expense type.
HTML Web Component
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group mds-form__field-group--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__field-group--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

Checkbox Group
Select one or more statistics to view. * You must select at least one statistic.
Checkbox Group
Average Minimum Maximum You must select at least one statistic.
HTML Web Component
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group mds-form__field-group--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--48535">
                <input id="average--48535" 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--91491">
                <input id="minimum--91491" 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--25798">
                <input id="maximum--25798" 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__field-group--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__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

When setting props as attributes on a custom HTML element, use kebab-case instead of camelCase.

Prop
Type
Validation
Default
Description

additionalClass

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.

size

String

One of: 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.

visible

Boolean

false

Sets the visibility of the field error.

Slots

Default Slot

Pass text in between the <mds-field-error></mds-field-error> tags to set the field error’s text content. This can be overridden with the text prop.

Events

Event Name
Description

mds-field-error-activated

Triggers when the visible prop is set to true.

mds-field-error-dismissed

Triggers when the visible prop is set to false.

Usage Examples

Setting id and size using props. Using the default slot for text content:

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

Implementation

  • Always include aria-live="assertive" 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.