Morningstar Design System

Labels

Variations Design Guidelines Code Reference Accessibility

Labels
updated

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

    2.16.0

Labels describe form elements and indicate whether they’re required or optional.

See Forms for guidance on composing full forms.

Variations Design Guidelines Code Reference Accessibility

Variations

Default

Use to describe a form input.

Default
Default
First Name
HTML Web Component 
<label class="mds-form__label"> First Name </label>
<mds-label for="[associated element id]">First Name</mds-label>

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

<!-- HTML -->
<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" />
</div>
<!-- Web Component -->
<mds-field-group>
    <mds-label for="first-name"> First Name </mds-label>
    <mds-input id="first-name" placeholder="First Name"></mds-input>
</mds-field-group>

Required

Use to indicate an input is required.

Required
Required
First Name
HTML Web Component 
<label class="mds-form__label"> First Name <abbr class="mds-form__label-required-indicator" title="This field is required." aria-label="This field is required.">*</abbr>
</label>
<mds-label for="[associated element id]" required>First Name</mds-label>

Optional

Use to indicate an input is optional.

Optional
Optional
First Name
HTML Web Component 
<label class="mds-form__label"> First Name<span class="mds-form__label-optional"> (Optional) </span>
</label>
<mds-label for="[associated element id]" optional>First Name</mds-label>

Sizing

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

Small
Medium (Default)
Large
Small
First Name
Medium (Default)
First Name
Large
First Name
HTML Web Component 
<label class="mds-form__label mds-form__label--small"> First Name <abbr class="mds-form__label-required-indicator" title="This field is required." aria-label="This field is required.">*</abbr>
</label>
<mds-label for="[associated element id]" required size="small">First Name</mds-label>

Don’t Use When

  • Providing details or requirements about a form field, like password requirements. Instead, use Microcopy.

Visual Language

  • Match the size of labels to the form element they’re paired with.

Editorial

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

CSS

Class References

Class
Applies to
Outcome

mds-form__label--small

mds-form__label

Applies small styles to the label text.

mds-form__label--large

mds-form__label

Applies large styles to the label text.

Web Component

Props

Prop
Type
Validation
Default
Description

class

String

—

—

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

for

String

Required

—

The id attribute for the associated form element, e.g. Textarea or Input.

id

String

—

—

The id attribute for the HTML element.

optional

String

—

false

If true, sets optional text to the right of the label with a default text of (Optional).

optionalText

String

—

(Optional)

Can be used to override the default optional text.

required

Boolean

—

false

If true, the required indicator is visible to the right of the label.

requiredText

String

—

This field is required.

If required is true, a default text of “This field is required.” will be provided for assistive technologies.

size

String

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

medium

Alters the size of the label.

text

String

Required

—

Text for the label.
  • Use kebab-case when setting props in HTML. For example, optionalText would be written as optional-text.

Slots

Default Slots

Any text or markup inside the <mds-label></mds-label> will be used as the label’s text content.

Named Slots

Slot Name
Description

mds-label-optional-text

Provided that optional="true", assigning slot="mds-label-optional-text" to any element within the <mds-label></mds-label> tags will render that element in the optional text slot of the label.

Usage Examples

Setting size, label text, for, and required status:

<!-- Using Props -->
<mds-label size="large" text="First Name" for="first-name-input" required="true"></mds-label>
<!-- Using Slots -->
<mds-label size="large" for="first-name-input" required="true"> First Name </mds-label>

Setting custom optional text:

<!-- Using Props -->
<mds-label text="Profesión" for="profession-select" optional="true" optional-text="(Opcional)"></mds-label>
<!-- Using Slots -->
<mds-label for="profession-select" optional="true"> Profesión <slot name="mds-label-optional-text">(Opcional)</slot>
</mds-label>

Implementation

  • Always include a label with each form element. See the Forms composition section for examples.
  • Include a for attribute on each label with a value matching the id attribute on the corresponding input, textarea or select.

Best Practices

  • Labels within Forms must always be visible.
  • Never use placeholder text in place of a label.