Morningstar Design System

Checkboxes

Variations Design Guidelines Code Reference Accessibility

Checkboxes
updated

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

    2.11.0

Checkboxes afford one or more selection from a set of options.

See Forms for guidance on composing full forms.

Variations Design Guidelines Code Reference Accessibility

Variations

Default

Use when affording a binary selection.

Unchecked, Default
Unchecked, Hover
Unchecked, Focus
Unchecked, Default
I accept the terms and conditions.
Unchecked, Hover
I accept the terms and conditions.
Unchecked, Focus
I accept the terms and conditions.
HTML Web Component 
<label class="mds-form__checkbox" for="i-accept-the-terms-and-conditions.--14892">
    <input id="i-accept-the-terms-and-conditions.--14892" 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="/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"> I accept the terms and conditions. </span>
    </span>
</label>
<mds-checkbox>I accept the terms and conditions.</mds-checkbox>
Unchecked, Disabled
Unchecked, Disabled
I accept the terms and conditions.
HTML Web Component 
<label class="mds-form__checkbox mds-form__checkbox--disabled" for="i-accept-the-terms-and-conditions.--80671">
    <input id="i-accept-the-terms-and-conditions.--80671" 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="/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"> I accept the terms and conditions. </span>
    </span>
</label>
<mds-checkbox disabled>I accept the terms and conditions.</mds-checkbox>
Checked, Default
Checked, Hover
Checked, Active
Checked, Focus
Checked, Default
I accept the terms and conditions.
Checked, Hover
I accept the terms and conditions.
Checked, Active
I accept the terms and conditions.
Checked, Focus
I accept the terms and conditions.
HTML Web Component 
<label class="mds-form__checkbox" for="i-accept-the-terms-and-conditions.--19430">
    <input id="i-accept-the-terms-and-conditions.--19430" 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="/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"> I accept the terms and conditions. </span>
    </span>
</label>
<mds-checkbox checked>I accept the terms and conditions.</mds-checkbox>
Checked, Disabled
Checked, Disabled
I accept the terms and conditions.
HTML Web Component 
<label class="mds-form__checkbox mds-form__checkbox--disabled" for="i-accept-the-terms-and-conditions.--1892">
    <input id="i-accept-the-terms-and-conditions.--1892" 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="/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"> I accept the terms and conditions. </span>
    </span>
</label>
<mds-checkbox checked disabled>I accept the terms and conditions.</mds-checkbox>

Without Label

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

Unchecked, Default
Unchecked, Hover
Unchecked, Focus
Unchecked, Active
Checked
Unchecked, Default
I accept the terms and conditions.
Unchecked, Hover
I accept the terms and conditions.
Unchecked, Focus
I accept the terms and conditions.
Unchecked, Active
I accept the terms and conditions.
Checked
I accept the terms and conditions.
HTML Web Component 
<label class="mds-form__checkbox mds-form__checkbox--hide-label" for="i-accept-the-terms-and-conditions--55081">
    <input id="i-accept-the-terms-and-conditions--55081" 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="/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"> I accept the terms and conditions </span>
    </span>
</label>
<mds-checkbox hidden-text="true">I accept the terms and conditions.</mds-checkbox>
  • 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.

Group

Use when affording multiple selections from a set of options.

Stacked
Select statistics to view. 
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group">
        <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--88075">
                <input id="average--88075" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-71149" />
                <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--71403">
                <input id="minimum--71403" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-71149" />
                <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--77805">
                <input id="maximum--77805" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-71149" />
                <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>
            <label class="mds-form__checkbox" for="medium--89196">
                <input id="medium--89196" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-71149" />
                <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"> Medium </span>
                </span>
            </label>
        </fieldset>
    </div>
</form>
Horizontal
Select statistics to view. 
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <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--73236">
                <input id="average--73236" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-71149" />
                <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--42851">
                <input id="minimum--42851" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-71149" />
                <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--93854">
                <input id="maximum--93854" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-71149" />
                <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>
            <label class="mds-form__checkbox" for="medium--4929">
                <input id="medium--4929" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-71149" />
                <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"> Medium </span>
                </span>
            </label>
        </fieldset>
    </div>
</form>
  • 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">Switch Group</a> for multiple selection.
Don‘t use a Switch Group for multiple selection.

Indeterminate

Use when affording a “Select All” option. After selecting all items, the indeterminate state is triggered once an option is deselected.

Indeterminate
Indeterminate
Indeterminate checkbox
HTML Web Component 
<label class="mds-form__checkbox" for="indeterminate-checkbox--64853">
    <input id="indeterminate-checkbox--64853" 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="/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"> 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--64853").indeterminate = true;
</script>
<mds-checkbox checked indeterminate="true">Indeterminate checkbox</mds-checkbox>

Sizing

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

Small

Medium (Default)

Large

Small
Checkbox Label
Checkbox Label
Medium (Default)
Checkbox Label
Checkbox Label
Large
Checkbox Label
Checkbox Label
HTML Web Component 
<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="/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"> Checkbox Label </span>
    </span>
</label>
<br>
<label class="mds-form__checkbox mds-form__checkbox--hide-label mds-form__checkbox--small" for="small-checkbox-without-label">
    <input id="small-checkbox-without-label" 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="/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"> Checkbox Label </span>
    </span>
</label>
<mds-checkbox size="small" id="small-wc-checkbox">Checkbox Label</mds-checkbox>
<br>
<mds-checkbox hidden-text="true" id="small-checkbox-wc-without-label">Checkbox Label</mds-checkbox>
  • Use the mds-form__checkbox-without-label class in conjunction with checkbox sizing modifier classes to render different sizes of the Without Label variation.

Use When

  • Affording a binary selection, like accepting terms and conditions.
  • Affording multiple selections from a set of options.
  • Enabling selection of an object, such as a Card.
  • Affording selection of a row within a Data Table.

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.

Visual Language

  • Uses the same :hover and :active styles as the primary Button when checked.

Behaviors

  • Reflects the affirmative (“yes” or “true”) of its label when checked.
  • Choices made via checkbox should always be submitted or saved using a Button.
  • A checkbox’s label is included in the clickable target area.

Editorial

Default

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

Groups

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

CSS

Class References

Class
 Applies to
 Outcome

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__checkbox--hide-label

mds-form__checkbox

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

Web Component

Props

Prop Type Validation Default Description

checked

Boolean

––

false

Sets the checked value of the checkbox.

class

String

––

––

A space-separated list of class names that will be appended to the default mds-form__checkbox element.

disabled

Boolean

––

false

If true, sets the disabled attribute on the checkbox, rendering it non-interactive, and applies disabled styling.

hiddenText

Boolean

––

false

When true, hides the checkbox's label.

id

String

Required

mds-checkbox--[random-number]

The id attribute for the HTML element.

indeterminate

Boolean

––

false

If true, renders the indeterminate state of the checkbox.

size

String

Enum: ["small", "medium", "large"]

medium

Alters the size of the checkbox.

text

String

Required

––

The checkbox label text.

value

String

Required

––

The checkbox value.
  • Use kebab-case when setting props in HTML. For example, hiddenLabel would be written as hidden-label.

Slots

Any text passed in between <mds-checkbox></mds-checkbox> tags will be used as the checkbox’s label. This slot can accept plain text, or a combination of text and link where appropriate. If no content is passed in via the slot and the text prop is empty, the checkbox label content will be empty.

Usage Examples

Setting size, checked status, and label text:

<!-- Using Props -->
<mds-checkbox size="small" text="I accept" checked></mds-checkbox>
<!-- Using Slots -->
<mds-checkbox size="small" checked> I accept </mds-checkbox>

Creating a checkbox with a hidden label:

<!-- Using Props -->
<mds-checkbox hidden-label="true" text="Portfolio 1"></mds-checkbox>
<!-- Using Slots -->
<mds-checkbox hidden-label="true"> Portfolio 1 </mds-checkbox>

Implementation