Morningstar Design System

Field Errors

Variations Design Guidelines Code Reference Accessibility
You are viewing legacy documentation. View the most recent documentation.

Field Errors

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

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

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.
Touch
This is example error text.
Small
This is example error text.
Medium (Default)
This is example error text.
Large
This is example error text.
Touch
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>
  • The large and touch sizes use the same styling.
  • See mixin documentation for additional details on how to create media queries to switch to the touch size.

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="#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--38296">
                <input id="average--38296" 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="#check--s">
                            </use>
                        </svg>
                        <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                            <use xlink:href="#minus--s">
                            </use>
                        </svg>
                    </span>
                    <span class="mds-form__checkbox-text">
                        Average
                    </span>
                </span>
            </label>
            <label class="mds-form__checkbox" for="minimum--98947">
                <input id="minimum--98947" 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="#check--s">
                            </use>
                        </svg>
                        <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                            <use xlink:href="#minus--s">
                            </use>
                        </svg>
                    </span>
                    <span class="mds-form__checkbox-text">
                        Minimum
                    </span>
                </span>
            </label>
            <label class="mds-form__checkbox" for="maximum--9403">
                <input id="maximum--9403" 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="#check--s">
                            </use>
                        </svg>
                        <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                            <use xlink:href="#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.

mds-form__field-error--touch

mds-form__field-error

Applies touch styles to the descriptive error text.

Mixins

Touch Properties

Use this mixin to create media queries in your product styles to switch field errors to their touch variation.

@include mds-field-error-touch-properties();
  • The mixin includes all CSS properties required to convert any size into the touch variation.
  • Uses the same styling as the large size.
  • When composing complex forms, consider using the @include mds-form-all-touch-properties(); mixin for efficiency.

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, touch

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.

Methods

Method Name
Description

show()

Deprecated, will be removed in v3.0. Use the visible prop instead. Shows the field error and triggers the mds-field-error-activated event.

hide()

Deprecated, will be removed in v3.0. Use the visible prop instead. Hides the field error and triggers the mds-field-error-dismissed event.

Events

Event Name
Description

mds-field-error-activated

Deprecated, will be removed in v3.0. Use the visible prop instead. Triggered when the show() method is called.

mds-field-error-dismissed

Deprecated, will be removed in v3.0. Use the visible prop instead. Triggered when the hide() method is called.

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 Tips

Set the visibility of an error

Set the visible prop to true to show the error text and wrap the Field Errors within Field Groups. When the field group’s error prop is set to true, the form element within the field group will switch to its visual error state (with the red underline).

See Example on Codepen

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.