Label
A Label provides a descriptive title for an input or form field.
Name | Value |
---|---|
Props | |
icon | |
optional | |
visuallyHidden | |
isLegend | |
disabled | |
Slots | |
default | |
description | |
View | |
Reading direction | |
Note: For icon properties, the relevant icon also needs to be imported from the @wikimedia/codex-icons package. See the usage documentation for more information. |
Overview
When to use Label
Every input or form field must have an associated label. When creating a form, use the Field component, which contains a Label. When creating an input outside of a form, such as a SearchInput), use the Label component.
For more detailed information about form fields, consult the guidelines for constructing forms.
About Label
Label includes the following elements.
Icon (optional)
A start icon can be included to visually enhance the label's context. Any Codex icon can be used.
- Use a simple icon that is easily comprehensible to users.
- Don't use an icon in the label if there is an icon in the input.
Label text
A clear and descriptive title for the input tells the user what information to enter.
- Keep the label text short, clear, and easy to scan.
- Label text is required, but can be visually-hidden if the context of an input is sufficient to identify it.
- Label text is bold by default, but the label of nested fields should use the regular font weight to make the hierarchy clear.
Optional indicator (optional)
Fields are assumed to be required by default. If a field is optional, it can be labeled as such.
- Ensure that the entire word "optional" is displayed for translation purposes.
- Don't mark required labels with an asterisk.
Description (optional)
The description provides additional information about the field.
Examples
TIP
Consider using the Field component, which includes the Label component and handles accessibility features like ARIA attributes internally. If you need more custom behavior, use the Label component on its own.
Basic usage
By default, the Label will be visible with the label text styled in bold.
Developer notes
When using the Label component with an input, make sure to add an id
attribute to the input and use that to set the for
attribute on the label. These attributes will be applied on the proper element within each component (in the example below, that's the <label>
for the Label component, and the <input>
for the TextInput).
Visually-hidden label
All inputs need a label to meet accessibility standards. In rare instances, you may not need a visible label if it's very clear from context how to use an input.
Developer notes
To achieve this, you can use the Label component to create a semantic label for assistive technology, but visually hide the label.
Note that this will hide the entire output of the component, including the description.
With description
Description text can include markup. Only links and text formatting are recommended as description text should be concise.
Label vs. legend
This component outputs a different HTML element depending on whether it is a label for a single input or for a group of inputs. Below are examples of a label and a legend with an associated description.
Developer notes
Label outputs a <label>
element by default. When the isLegend
prop is set to true
, it will instead output a <legend>
element. Use this within a <fieldset>
element.
There is a named slot in the Label component, description
, for including more information about the field. It's important to note that, when isLegend
is true
, the description will be rendered inside the <legend>
element to ensure it will be read by assistive technology.
Technical implementation
Vue usage
Props
Prop name | Description | Type | Default |
---|---|---|---|
icon | Icon before the label text. Do not use this if including a start icon within the input component. | Icon|null | null |
optional | Whether the field is optional. This will add a flag next to the label indicating that the field is optional. | boolean | false |
optionalFlag | Text to indicate that the field is optional. Omit this prop to use the default value, "(optional)". | string | '' |
visuallyHidden | Whether the label should be visually hidden. | boolean | false |
isLegend | Whether this component should output a <legend> element.Always set this to true when this component is used inside a <fieldset> element. Do not set it to true otherwise. | boolean | false |
inputId | The ID of the input/control this label is for. Will be added as the for attribute of the <label> . Not needed for <legend> . | string | '' |
descriptionId | The ID of the description element. This ID can be used for the aria-describedby attribute of the input. | string | '' |
disabled | Whether this label is for a disabled field or input. | boolean | false |
Slots
Name | Description | Bindings |
---|---|---|
default | Label text. | |
description | Short description text. |
CSS-only version
Markup structure
Examples are shown with inputs to demonstrate the ARIA attributes required to connect the label and input.
Label
Use a <label>
element for a single input.
Legend
Inside a <form>
, use a <legend>
element within a <fieldset>
for input groups.
When outputting a <legend>
rather than a <label>
, the markup of this component is quite different:
- There is no wrapper
<div>
—<legend>
must be a direct child of<fieldset>
- The description is included inside the
<legend>
- The
for
andaria-describedby
attributes are not needed
With icon
To add an icon to the label:
- Add an empty
<span>
before the label text with the classes.cdx-label__label__icon
and a custom class that you can target to add the CSS-only icon - Apply the CSS-only icon mixin to that
<span>
This works for <label>
and <legend>
.
Visually-hidden
Occasionally, there may be a use case for the label to be visually hidden. In these cases, it should still be present in the DOM with appropriate elements and ARIA attributes.
To visually hide the label, add the .cdx-label--visually-hidden
class to the outer element. This works for <label>
and <legend>
.
Disabled
Add the .cdx-label--disabled
class to the outer element to get disabled styles. This works for <label>
and <legend>
.
Keyboard navigation
Key | Function |
---|---|
Enter | If the focus is placed on one of the interactive elements within the Label, it activates them. |