Label

A Label provides a descriptive title for an input or form field.

Working in progress

This component is still under development. It is not yet available in releases of Atlas.

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 use the Label component.

For more detailed information about form fields, consult the guidelines for constructing forms.

About Label

Label includes the following elements.

Label text

A clear and descriptive title for the input tells the user what information to enter.

• Do: Keep the label text short, clear, and easy to scan.
• Do: Label text is required, but can be visually-hidden if the context of an input is sufficient to identify it.
• Do: 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.

• Do: Ensure that the entire word "optional" is displayed for translation purposes.
• Don't: 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.

<AtlLabel
  id="username"
  label="Username"
/>

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.

<AtlLabel
  id="search"
  label="Search"
  visuallyHidden={true}
/>

With description

Description text can include markup. Only links and text formatting are recommended as description text should be concise.

<AtlLabel
  id="email"
  label="Email"
  description="Enter your work email address. We’ll never share it."
/>

• Do: Explain what users should do to use this element effectively.
• Don't: Highlight what users should avoid when using this element.

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.

Label

<AtlLabel
  id="first-name"
  label="First Name"
  description="As it appears on your ID."
/>

Legend

<AtlLabel
  isLegend={true}
  label="Preferred Contact Method"
  description="Select all that apply."
/>

Technical implementation

Props

Prop Name	Description	Type	Default
id	The ID of the label element itself. Useful for accessibility or testing.	string	''
label	Label text for the input or field.	string	'Label'
icon	Icon displayed before the label text. Do not use if the input already has a startIcon.	string | null	null
optional	Adds an optional flag next to the label if set to true.	boolean	false
optionalFlag	Text to indicate that the field is optional. Defaults to "(optional)" when optional is true.	string	''
visuallyHidden	Visually hides the label text but keeps it accessible for screen readers. The description is also hidden when this is true.	boolean	false
isLegend	Renders a <legend> element instead of a <label> when true. Required when the label is inside a <fieldset>.	boolean	false
disabled	Indicates that the associated input is disabled. Updates the label style accordingly.	boolean	false
required	Marks the input or field as required visually.	boolean	false
description	Short descriptive text that appears below the label.	string	''
inputId	The ID of the input/control this label is associated with. Sets the for attribute on <label>. Not used when isLegend is true.	string	''
descriptionId	The ID of the description text. Used to link with aria-describedby for accessibility purposes on the input/control.	string	''

Slots

Slot Name	Description	Bindings
default	Label text. Overrides the label prop if used.	—
description	Short description or hint below the label. Overrides description prop.	—

Keyboard navigation

Key	Function
Enter	If the focus is placed on one of the interactive elements within the Label, it activates them.