Forms

Forms gather information from users via inputs, such as text boxes, text areas, selects, checkboxes, and radio buttons. Labels sit atop these inputs.

Variations

Label

Use to describe a form input and indicate whether the input is required or optional.

Default
<label class="mds-form__label"> First Name </label>
Required
<label class="mds-form__label"> First Name
    <abbr class="mds-form__label-required-indicator" title="This field is required." aria-hidden="true">*</abbr>
    <span class="mds-screenreader-only">Required Field.</span>
</label>
Optional
<label class="mds-form__label"> First Name
    <span class="mds-form__label-optional"> (Optional) </span>
</label>

Editorial

  • Use title case.
  • Clearly written labels should eliminate the need for placeholder text in text boxes and text areas.

Text Box

Use to solicit a short, single line of text or a number.

Default
Hover
Focus
<input class="mds-form__input" type="text">
Disabled
<input class="mds-form__input" type="text" disabled>
With Placeholder
<input class="mds-form__input" type="text" placeholder="First Name">
  • Use when the user must enter a name, email address, phone number, street address, age, salary, etc.
  • Never use for multiple lines of text. Instead, use a text area.
  • Never use to perform a search. Instead, use a Search Field.
  • Avoid using placeholder text by making sure the label above the text box is clear. If you still need additional instructional context, consider a Tooltip next to the label header or microcopy under the label, so the helper content doesn’t disappear when a user starts typing.
  • Placeholder text disappears when a user types in the input. If a user doesn’t enter a value and moves to another part of a form, the placeholder text should reappear in the former text box.
  • In IE11, placeholder text is cleared on focus. This is default IE11 behavior and a known issue, teams are still encouraged to use text boxes in production.

Editorial

  • Placeholder text should be active. Start the text with a verb.
  • Don’t end placeholder text in text boxes with a period.
  • Use title case for placeholder text.

Text Area

Use when soliciting multiple lines of text.

Default
<textarea class="mds-form__textarea"></textarea>
Disabled
<textarea class="mds-form__textarea" disabled></textarea>
With Placeholder
<textarea class="mds-form__textarea" placeholder="Tell us more here..."></textarea>
  • Never use for short, single lines of text. Instead, use a text box.
  • Include placeholder text to indicate what information belongs in the text area. Placeholder text disappears when the user types in the text area. If the user doesn’t enter a value and moves to another part of a form, the placeholder text should reappear in the former text box.
  • In IE11, placeholder text is cleared on focus. This is default IE11 behavior and a known issue, teams are still encouraged to use text areas in production.

Editorial

  • Placeholder text in text areas should be full sentences with punctuation.
  • Don’t use title case here.

Select (Dropdown)

Use when affording a single selection from a predefined list of options.

Default
<div class="mds-form__select">
    <select class="mds-form__select-input">
        <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="/assets/icons/mds_icons.svg#caret-down--s"> </use>
        </svg>
    </span>
</div>
Disabled
<div class="mds-form__select mds-form__select-input--disabled">
    <select class="mds-form__select-input" disabled>
        <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="/assets/icons/mds_icons.svg#caret-down--s"> </use>
        </svg>
    </span>
</div>
  • Always display a user’s selected option after a choice is made.
  • Never use for a list of options exceeding 10 items. Instead, use a Combo Box.
  • Never use for a list of only two options. Instead, use a radio group or a Switch.

Editorial

  • Display either “Select an Option” or no text at all as the default selected option.
  • Start the text with a verb.
  • Don’t end text in a select with a period.
  • Keep option names as brief as possible - aim for under 5 words.
  • Use title case.

Checkbox

Use when affording a binary selection.

Unchecked, Default
Unchecked, Hover
Unchecked, Focus
<label class="mds-form__checkbox" for="i-accept-the-terms-and-conditions.--92834">
    <input id="i-accept-the-terms-and-conditions.--92834" type="checkbox" class="mds-form__checkbox-input" />
    <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="/assets/icons/mds_icons.svg#check--s"> </use>
            </svg>
            <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
            </svg>
        </span>
        <span class="mds-form__checkbox-text"> I accept the terms and conditions. </span>
    </span>
</label>
Unchecked, Disabled
<label class="mds-form__checkbox mds-form__checkbox--disabled" for="i-accept-the-terms-and-conditions.--95052">
    <input id="i-accept-the-terms-and-conditions.--95052" type="checkbox" class="mds-form__checkbox-input" disabled />
    <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="/assets/icons/mds_icons.svg#check--s"> </use>
            </svg>
            <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
            </svg>
        </span>
        <span class="mds-form__checkbox-text"> I accept the terms and conditions. </span>
    </span>
</label>
Checked, Default
Checked, Hover
Checked, Active
Checked, Focus
<label class="mds-form__checkbox" for="i-accept-the-terms-and-conditions.--70397">
    <input id="i-accept-the-terms-and-conditions.--70397" type="checkbox" class="mds-form__checkbox-input" checked />
    <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="/assets/icons/mds_icons.svg#check--s"> </use>
            </svg>
            <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
            </svg>
        </span>
        <span class="mds-form__checkbox-text"> I accept the terms and conditions. </span>
    </span>
</label>
Checked, Disabled
<label class="mds-form__checkbox mds-form__checkbox--disabled" for="i-accept-the-terms-and-conditions.--54421">
    <input id="i-accept-the-terms-and-conditions.--54421" type="checkbox" class="mds-form__checkbox-input" checked disabled />
    <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="/assets/icons/mds_icons.svg#check--s"> </use>
            </svg>
            <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
            </svg>
        </span>
        <span class="mds-form__checkbox-text"> I accept the terms and conditions. </span>
    </span>
</label>
  • Reflects the affirmative (“yes” or “true”) of its label when checked.
  • Choices made via checkbox should always be submitted or saved using a Button.
  • Follows the same :hover and :active conventions as the primary Button when checked.
  • Include the label in the checkbox's clickable target area.

Don't Use When

  • Turning a feature, mode, or functionality on and off. Instead, use a Switch.
  • Checking or unchecking elicits an immediate change in the UI or functionality, such as enabling a disabled field or revealing more controls. Instead, use a Switch.
  • Checking or unchecking elicits a change in background functionality without affecting the UI, like disabling an email notification. Instead, use a Switch.

Editorial

  • Use full sentences with punctuation.
  • If user is consenting to something, start the sentence with “I”, and also run the phrasing you choose by compliance.

Checkbox Without Label

Use when enabling selection of an object such as a card.

Unchecked, Default
Unchecked, Hover
Unchecked, Focus
Unchecked, Active
Checked
<label class="mds-form__checkbox mds-form__checkbox--hide-label" for="i-accept-the-terms-and-conditions--79556">
    <input id="i-accept-the-terms-and-conditions--79556" type="checkbox" class="mds-form__checkbox-input" />
    <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="/assets/icons/mds_icons.svg#check--s"> </use>
            </svg>
            <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
            </svg>
        </span>
        <span class="mds-form__checkbox-text"> I accept the terms and conditions </span>
    </span>
</label>
  • Always include an associated <label> element, even if it is hidden from the screen.
  • Position the checkbox without label in the upper left corner of an object.
  • Distinguish the selected state of the overall object (such as a card) by changing the object's visual style, such as altering the background or border color.
  • Omit margins from the checkbox element to prevent focused and active states from appearing as larger than the checkbox itself.
Do include a checkbox without label to enable selection of a larger object, such as a strategy, security or fund.
Do include a checkbox without label to enable selection of a larger object, such as a strategy, security or fund.

Checkbox Group

Stacked
Select statistics to view.
<fieldset class="mds-form__checkbox-group" role="group">
    <legend class="mds-form__checkbox-group-label"> Select statistics to view. </legend>
    <label class="mds-form__checkbox" for="average--90523">
        <input id="average--90523" type="checkbox" class="mds-form__checkbox-input" />
        <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="/assets/icons/mds_icons.svg#check--s"> </use>
                </svg>
                <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                    <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                </svg>
            </span>
            <span class="mds-form__checkbox-text"> Average </span>
        </span>
    </label>
    <label class="mds-form__checkbox" for="minimum--90803">
        <input id="minimum--90803" type="checkbox" class="mds-form__checkbox-input" />
        <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="/assets/icons/mds_icons.svg#check--s"> </use>
                </svg>
                <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                    <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                </svg>
            </span>
            <span class="mds-form__checkbox-text"> Minimum </span>
        </span>
    </label>
    <label class="mds-form__checkbox" for="maximum--45024">
        <input id="maximum--45024" type="checkbox" class="mds-form__checkbox-input" />
        <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="/assets/icons/mds_icons.svg#check--s"> </use>
                </svg>
                <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                    <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                </svg>
            </span>
            <span class="mds-form__checkbox-text"> Maximum </span>
        </span>
    </label>
    <label class="mds-form__checkbox" for="medium--86143">
        <input id="medium--86143" type="checkbox" class="mds-form__checkbox-input" />
        <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="/assets/icons/mds_icons.svg#check--s"> </use>
                </svg>
                <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                    <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                </svg>
            </span>
            <span class="mds-form__checkbox-text"> Medium </span>
        </span>
    </label>
</fieldset>
Horizontal
Select statistics to view.
<div class="mds-form__field-group mds-form__field-group--horizontal">
    <fieldset class="mds-form__checkbox-group" role="group">
        <legend class="mds-form__checkbox-group-label"> Select statistics to view. </legend>
        <label class="mds-form__checkbox" for="average--4478">
            <input id="average--4478" type="checkbox" class="mds-form__checkbox-input" />
            <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="/assets/icons/mds_icons.svg#check--s"> </use>
                    </svg>
                    <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                        <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                    </svg>
                </span>
                <span class="mds-form__checkbox-text"> Average </span>
            </span>
        </label>
        <label class="mds-form__checkbox" for="minimum--59588">
            <input id="minimum--59588" type="checkbox" class="mds-form__checkbox-input" />
            <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="/assets/icons/mds_icons.svg#check--s"> </use>
                    </svg>
                    <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                        <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                    </svg>
                </span>
                <span class="mds-form__checkbox-text"> Minimum </span>
            </span>
        </label>
        <label class="mds-form__checkbox" for="maximum--10552">
            <input id="maximum--10552" type="checkbox" class="mds-form__checkbox-input" />
            <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="/assets/icons/mds_icons.svg#check--s"> </use>
                    </svg>
                    <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                        <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                    </svg>
                </span>
                <span class="mds-form__checkbox-text"> Maximum </span>
            </span>
        </label>
        <label class="mds-form__checkbox" for="medium--57212">
            <input id="medium--57212" type="checkbox" class="mds-form__checkbox-input" />
            <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="/assets/icons/mds_icons.svg#check--s"> </use>
                    </svg>
                    <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                        <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                    </svg>
                </span>
                <span class="mds-form__checkbox-text"> Medium </span>
            </span>
        </label>
    </fieldset>
</div>
  • Include a label to describe the options within the group.
  • Options can be selected independently.
Do use when affording a user multiple choices from a set of options.
Do use when affording a user multiple choices from a set of options.
Don‘t use a <a class="mds-link" href="/components/switches.html#switch-group-1">Switch Group</a>
Don‘t use a Switch Group
Indeterminate
<label class="mds-form__checkbox" for="indeterminate-checkbox--94239">
    <input id="indeterminate-checkbox--94239" type="checkbox" class="mds-form__checkbox-input" checked />
    <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="/assets/icons/mds_icons.svg#check--s"> </use>
            </svg>
            <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
            </svg>
        </span>
        <span class="mds-form__checkbox-text"> Indeterminate checkbox </span>
    </span>
</label>
<!-- Something like the following Javascript would be required to set an indeterminate state on a checkbox -->
<script>
    document.getElementById("indeterminate-checkbox--94239").indeterminate = true;
</script>
  • Use the indeterminate variation when affording a “Select All” option. After selecting all items, the indeterminate state is triggered once an option is deselected.

Editorial

  • Use full sentences with punctuation for the checkbox group label.
  • Try to keep checkbox labels brief and start them with verbs.

Radio Button

Use to afford a single selection from two or more options.

Unselected, Default
Unselected, Hover
Unselected, Focus
<label class="mds-form__radio-button" for="peer-group--34199">
    <input id="peer-group--34199" name="undefined-basic-example" value="blue" type="radio" class="mds-form__radio-button-input" />
    <span class="mds-form__radio-button-visible-wrap">
        <span class="mds-form__radio-button-visual"></span>
        <span class="mds-form__radio-button-text "> Peer Group </span>
    </span>
</label>
Unselected, Disabled
<label class="mds-form__radio-button mds-form__radio-button--disabled" for="peer-group--36233">
    <input id="peer-group--36233" name="undefined-basic-example" value="blue" type="radio" class="mds-form__radio-button-input" disabled />
    <span class="mds-form__radio-button-visible-wrap">
        <span class="mds-form__radio-button-visual"></span>
        <span class="mds-form__radio-button-text "> Peer Group </span>
    </span>
</label>
Selected, Default
Selected, Hover
Selected, Active
Selected, Focus
<label class="mds-form__radio-button" for="choose-this-one--71849">
    <input id="choose-this-one--71849" name="radio-example-1" value="blue" type="radio" class="mds-form__radio-button-input" checked />
    <span class="mds-form__radio-button-visible-wrap">
        <span class="mds-form__radio-button-visual"></span>
        <span class="mds-form__radio-button-text "> Choose this one </span>
    </span>
</label>
Selected, Disabled
<label class="mds-form__radio-button mds-form__radio-button--disabled" for="peer-group--35590">
    <input id="peer-group--35590" name="undefined-basic-example-checked" value="blue" type="radio" class="mds-form__radio-button-input" checked disabled />
    <span class="mds-form__radio-button-visible-wrap">
        <span class="mds-form__radio-button-visual"></span>
        <span class="mds-form__radio-button-text "> Peer Group </span>
    </span>
</label>

Radio Group

Stacked
Rank Within
<fieldset class="mds-form__radio-button-group" role="radiogroup">
    <legend class="mds-form__radio-button-group-label"> Rank Within </legend>
    <label class="mds-form__radio-button" for="id-68136-basic-example-checked">
        <input id="id-68136-basic-example-checked" name="id-68136" value="blue" type="radio" class="mds-form__radio-button-input" checked />
        <span class="mds-form__radio-button-visible-wrap">
            <span class="mds-form__radio-button-visual"></span>
            <span class="mds-form__radio-button-text "> Your List </span>
        </span>
    </label>
    <label class="mds-form__radio-button" for="id-68136-basic-example">
        <input id="id-68136-basic-example" name="id-68136" value="blue" type="radio" class="mds-form__radio-button-input" />
        <span class="mds-form__radio-button-visible-wrap">
            <span class="mds-form__radio-button-visual"></span>
            <span class="mds-form__radio-button-text "> Peer Group </span>
        </span>
    </label>
</fieldset>
Horizontal
Rank Within
<div class="mds-form__field-group mds-form__field-group--horizontal">
    <fieldset class="mds-form__radio-button-group" role="radiogroup">
        <legend class="mds-form__radio-button-group-label"> Rank Within </legend>
        <label class="mds-form__radio-button" for="id-34759-basic-example-checked">
            <input id="id-34759-basic-example-checked" name="id-34759" value="blue" type="radio" class="mds-form__radio-button-input" checked />
            <span class="mds-form__radio-button-visible-wrap">
                <span class="mds-form__radio-button-visual"></span>
                <span class="mds-form__radio-button-text "> Your List </span>
            </span>
        </label>
        <label class="mds-form__radio-button" for="id-34759-basic-example">
            <input id="id-34759-basic-example" name="id-34759" value="blue" type="radio" class="mds-form__radio-button-input" />
            <span class="mds-form__radio-button-visible-wrap">
                <span class="mds-form__radio-button-visual"></span>
                <span class="mds-form__radio-button-text "> Peer Group </span>
            </span>
        </label>
    </fieldset>
</div>
  • Use when seeing all available options is critical. If the options are secondary in importance, consider using the select form element.
  • When possible, use the stacked variation. Options are harder to differentiate within the horizontal group.
  • If selecting no option is a viable choice, include a radio button within the group with an appropriate label, i.e. “None”.
  • A selected radio button follows the same :hover and :active conventions as the primary Button.
  • A radio button’s label is part of the clickable area of the control.
  • Add name attribute for Radio Group to group radio buttons together and ensures that a single selection is achieved.
  • Generally, the first option in the radio group should be selected by default. If preselection of an option can result in incorrect assumptions, i.e., “Male” or “Female”, then no option should be selected by default.

Editorial

  • For the radio group label, use full sentences with punctuation.
  • Try to keep radio button labels brief and start them with verbs.

Required-Fields Key

Use to describe the required-field indicator symbol.

Default
Required fields
<form class="mds-form" method="post" action="form/processor">
    <span class="mds-form__required-fields-key">Required fields</span>
    <div class="mds-form__field-group">
        <label class="mds-form__label" for="required-first-name"> First Name
            <abbr class="mds-form__label-required-indicator" title="This field is required." aria-hidden="true">*</abbr>
            <span class="mds-screenreader-only">Required Field.</span>
        </label>
        <input class="mds-form__input" type="text" id="required-first-name"> </div>
</form>

Errors

Use to indicate form elements with invalid or missing entries, including a description of the error.

Text Box
This is placeholder error messaging.
<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-hidden="true">*</abbr>
        <span class="mds-screenreader-only">Required Field.</span>
    </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"> This is placeholder error messaging. </span>
    </span>
</div>
Text Area
This is placeholder error messaging.
<div class="mds-form__field-group mds-form--error">
    <label class="mds-form__label" for="error-textarea"> Comments
        <abbr class="mds-form__label-required-indicator" title="This field is required." aria-hidden="true">*</abbr>
        <span class="mds-screenreader-only">Required Field.</span>
    </label>
    <textarea class="mds-form__textarea" id="error-textarea" aria-describedby="textarea-error" aria-invalid="true"></textarea>
    <span class="mds-form__field-error" id="textarea-error" role="alert">
        <span class="mds-form__field-error-text"> This is placeholder error messaging. </span>
    </span>
</div>
Select (Dropdown)
This field is required
<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-hidden="true">*</abbr>
        <span class="mds-screenreader-only">Required Field.</span>
    </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="/assets/icons/mds_icons.svg#caret-down--s"> </use>
            </svg>
        </span>
    </div>
    <span class="mds-form__field-error" role="alert">
        <span class="mds-form__field-error-text"> This field is required </span>
    </span>
</div>
Checkbox
Select one or more statistics to view. Required Field. You must select at least one statistic.
<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-hidden="true">*</abbr>
            <span class="mds-screenreader-only">Required Field.</span>
        </legend>
        <label class="mds-form__checkbox" for="average--14670">
            <input id="average--14670" 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="/assets/icons/mds_icons.svg#check--s"> </use>
                    </svg>
                    <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                        <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                    </svg>
                </span>
                <span class="mds-form__checkbox-text"> Average </span>
            </span>
        </label>
        <label class="mds-form__checkbox" for="minimum--74618">
            <input id="minimum--74618" 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="/assets/icons/mds_icons.svg#check--s"> </use>
                    </svg>
                    <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                        <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                    </svg>
                </span>
                <span class="mds-form__checkbox-text"> Minimum </span>
            </span>
        </label>
        <label class="mds-form__checkbox" for="maxiumum--88448">
            <input id="maxiumum--88448" 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="/assets/icons/mds_icons.svg#check--s"> </use>
                    </svg>
                    <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                        <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                    </svg>
                </span>
                <span class="mds-form__checkbox-text"> Maxiumum </span>
            </span>
        </label>
        <label class="mds-form__checkbox" for="medium--73443">
            <input id="medium--73443" 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="/assets/icons/mds_icons.svg#check--s"> </use>
                    </svg>
                    <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                        <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                    </svg>
                </span>
                <span class="mds-form__checkbox-text"> Medium </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>
Radio Button
Select what you would like to rank within. Required Field. You must choose an option.
<div class="mds-form__field-group mds-form--error">
    <fieldset class="mds-form__radio-button-group" role="radiogroup">
        <legend class="mds-form__radio-button-group-label"> Select what you would like to rank within.
            <abbr class="mds-form__label-required-indicator" title="Please select an option." aria-hidden="true">*</abbr>
            <span class="mds-screenreader-only">Required Field.</span>
        </legend>
        <label class="mds-form__radio-button" for="your-list--66931">
            <input id="your-list--66931" name="group-name" value="blue" type="radio" class="mds-form__radio-button-input" aria-describedby="radio-button-error-message" aria-invalid="true" />
            <span class="mds-form__radio-button-visible-wrap">
                <span class="mds-form__radio-button-visual"></span>
                <span class="mds-form__radio-button-text "> Your List </span>
            </span>
        </label>
        <label class="mds-form__radio-button" for="peer-group--70201">
            <input id="peer-group--70201" name="group-name" value="blue" type="radio" class="mds-form__radio-button-input" aria-describedby="radio-button-error-message, invalid=true" />
            <span class="mds-form__radio-button-visible-wrap">
                <span class="mds-form__radio-button-visual"></span>
                <span class="mds-form__radio-button-text "> Peer Group </span>
            </span>
        </label>
        <span class="mds-form__field-error" id="radio-button-error-message" role="alert">
            <span class="mds-form__field-error-text"> You must choose an option. </span>
        </span>
    </fieldset>
</div>
  • 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.

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 are the reason they can’t proceed, apologize.
  • 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 support@morningstar.com.”

Microcopy

Augment a label to describe a form element in greater detail.

Default
Your password must contain a letter and a number.
<div class="mds-form__field-group">
    <label class="mds-form__label" for="password-with-microcopy"> Password </label>
    <span class="mds-form__microcopy" id="password-help-text"> Your password must contain a letter and a number. </span>
    <input class="mds-form__input" type="password" id="password-with-microcopy" aria-describedby="password-help-text"> </div>
Below Field
Your password must contain a letter and a number.
<div class="mds-form__field-group">
    <label class="mds-form__label" for="password-with-microcopy"> Password </label>
    <input class="mds-form__input" type="password" id="password-with-microcopy" aria-describedby="password-help-text">
    <span class="mds-form__microcopy" id="password-help-text"> Your password must contain a letter and a number. </span>
</div>

Editorial

  • Use full sentences with punctuation.
  • Aim for no more than two sentences.

Sizing

Sizing affects element size, text size and internal spacing. The default size is medium, and you can use a modifier class to make each form element smaller (mds-form__{element name}--small) or larger (mds-form__{element name}--large).

Small
Medium
Large
<div class="mds-form__field-group">
    <input class="mds-form__input mds-form__input--small" type="text" id="small-text-box" placeholder="First Name"> </div>
<div class="mds-form__field-group">
    <textarea class="mds-form__textarea mds-form__textarea--small" id="small-textarea" placeholder="Tell us more here..."></textarea>
</div>
<div class="mds-form__field-group">
    <div class="mds-form__select mds-form__select--small">
        <select class="mds-form__select-input" id="small-select">
            <option class="mds-form__select-option" value="">Select an option</option>
            <option class="mds-form__select-option" value="option_1">Option 1</option>
            <option class="mds-form__select-option" value="option_2">Option 2</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="/assets/icons/mds_icons.svg#caret-down--s"> </use>
            </svg>
        </span>
    </div>
</div>
<div class="mds-form__field-group">
    <label class="mds-form__checkbox mds-form__checkbox--small" for="small-checkbox">
        <input id="small-checkbox" type="checkbox" class="mds-form__checkbox-input" />
        <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="/assets/icons/mds_icons.svg#check--s"> </use>
                </svg>
                <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                    <use xlink:href="/assets/icons/mds_icons.svg#minus--s"> </use>
                </svg>
            </span>
            <span class="mds-form__checkbox-text"> I accept the terms and conditions. </span>
        </span>
    </label>
</div>
<div class="mds-form__field-group">
    <label class="mds-form__radio-button mds-form__radio-button--small" for="small-radio-button">
        <input id="small-radio-button" name="group-name" value="blue" type="radio" class="mds-form__radio-button-input" />
        <span class="mds-form__radio-button-visible-wrap">
            <span class="mds-form__radio-button-visual"></span>
            <span class="mds-form__radio-button-text "> Peer Group </span>
        </span>
    </label>
</div>
  • Use the mds-form__checkbox-without-label class in conjunction with checkbox sizing modifier classes to render different sizes of the checkbox without label.

Guidelines

Accessibility

  • Always include a label with each form element.
  • Include a for attribute on each label with a value matching the id attribute on the corresponding input, textarea or select.
  • Use placeholder text to provide an example of the type of input you need from the user. For example, if you need a phone number in a certain format, include xxx-xxx-xxxx as placeholder text.
  • Never use placeholder text in place of a label.
  • Include an aria-describedby attribute on each input, textarea, or select that has an .mds-form__microcopy or 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__microcopy or .mds-form__field-error component.
  • Always include role=alert on .mds-form__field-error components.
  • Form Labels must always be visible.
  • Add aria-invalid="true" to an element where a validation error has occurred.
  • Ensure all Form elements are keyboard accessible.
  • Use fieldset and legend for grouped Form elements, such as Radio Buttons and Checkboxes.

Code Reference

CSS Class References

Class
Applies to
Outcome

.mds-form__field-group--horizontal

.mds-form__field-group

Changes the layout of form fields from vertical to horizontal.

.mds-form--error

.mds-form__input
.mds-form__textarea
.mds-form__select

Applies the MDS form error styles to input, textarea, and select.

.mds-form__input--small

.mds-form__input

Adjusts styling to render a small text box (input).

.mds-form__input--large

.mds-form__input

Adjusts styling to render a large text box (input).

.mds-form__textarea--small

.mds-form__textarea

Adjusts styling to render a small text area.

.mds-form__textarea--large

.mds-form__textarea

Adjusts styling to render a large text area.

.mds-form__select--small

.mds-form__select

Adjusts styling to render a small select.

.mds-form__select--large

.mds-form__select

Adjusts styling to render a large select.

.mds-form__checkbox--small

.mds-form__checkbox

Adjusts styling to render a small checkbox.

.mds-form__checkbox--large

.mds-form__checkbox

Adjusts styling to render a large checkbox.

.mds-form__radio-button--small

.mds-form__radio-button

Adjusts styling to render a small radio button.

.mds-form__radio-button--large

.mds-form__radio-button

Adjusts styling to render a large radio button.

.mds-form__checkbox--hide-label

.mds-form__checkbox

Hides label text, although screen readers can still access it.

©2017 Morningstar, Inc. All rights reserved. Terms of Use