Morningstar Design System

Labels

Variations Design Guidelines Code Reference Accessibility

Labels
updated

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

    2.23.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" for="associated-element-id">
    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" for="associated-element-id">
    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" for="associated-element-id">
    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" for="associated-element-id">
    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

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__label class.

for

String

Required

—

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

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

One of: small, medium, large

medium

Alters the size of the label.

text

String

Required

—

The text for the label. Can also be passed via the default slot.

Slots

Default Slots

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

Named Slots

Slot Name
Description

mds-label-optional-text

If optional is true, displays text in place of the default optional label.

Usage Examples

Setting size, text, for, and required via props:

<mds-label size="large" text="First Name" for="first-name-input" required></mds-label>

Setting for and optional via props. Using named slots for mds-label-optional-text:

<mds-label for="profession-select" optional>
    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.