@spectrum-web-components/field-label

Overview

An <sp-field-label> provides accessible labelling for form elements. Use the for attribute to outline the id of an element in the same DOM tree to which it should associate itself. Field labels give context to information that a user needs to input and are commonly used in forms to provide users with clear guidance about what information is required.

Usage

yarn add @spectrum-web-components/field-label

Import the side effectful registration of <sp-field-label> via:

import '@spectrum-web-components/field-label/sp-field-label.js';

When looking to leverage the FieldLabel base class as a type and/or for extension purposes, do so via:

import { FieldLabel } from '@spectrum-web-components/field-label';

Anatomy

Field labels can be associated with form elements by using the for attribute, which should reference the id of the related input element.

<sp-field-label for="email">Email address</sp-field-label>
<sp-textfield id="email" placeholder="[e-mail]"></sp-textfield>

Field labels can also be used to label a group of related inputs:

<sp-field-label for="account-type">Account type</sp-field-label>
<sp-radio-group id="account-type">
    <sp-radio value="admin">Admin</sp-radio>
    <sp-radio value="member" checked>Member</sp-radio>
    <sp-radio value="guest">Guest</sp-radio>
</sp-radio-group>

Options

Sizes

Small

<sp-field-label for="lifestory-0" size="s">Life Story (Small)</sp-field-label>
<sp-textfield
    placeholder="Enter your life story"
    id="lifestory-0"
    size="s"
></sp-textfield>

Medium

<sp-field-label for="lifestory-1" size="m">Life Story (Medium)</sp-field-label>
<sp-textfield
    placeholder="Enter your life story"
    id="lifestory-1"
    size="m"
></sp-textfield>

Large

<sp-field-label for="lifestory-2" size="l">Life Story (Large)</sp-field-label>
<sp-textfield
    placeholder="Enter your life story"
    id="lifestory-2"
    size="l"
></sp-textfield>

Extra Large

<sp-field-label for="lifestory-3" size="xl">
    Life Story (Extra Large)
</sp-field-label>
<sp-textfield
    placeholder="Enter your life story"
    id="lifestory-3"
    size="xl"
></sp-textfield>

Label Position

Field labels can be positioned either on top of an input (default) or to the side of an input. The top position is recommended for most cases as it works better with long text, localization, and responsive layouts.

Using the side-aligned attribute will display the <sp-field-label> element inline with surrounding elements and the start and end values outline the alignment of the label text in the width specified.

Top (Default)

<sp-field-label for="country-top">Country</sp-field-label>
<sp-textfield placeholder="Enter your country" id="country-top"></sp-textfield>

Side (Start Aligned)

Use side-aligned="start" to display the <sp-field-label> inline and to align the label text to the "start" of the flow of text:

<sp-field-label for="lifestory-1" side-aligned="start" style="width: 120px">
    Life Story
</sp-field-label>
<sp-textfield
    placeholder="Enter your life story"
    id="lifestory-1"
></sp-textfield>
<br />
<br />
<sp-field-label
    for="birth-place-1"
    side-aligned="start"
    required
    style="width: 120px"
>
    Birthplace
</sp-field-label>
<sp-picker id="birth-place-1">
    <span slot="label">Choose a location:</span>
    <sp-menu-item>Istanbul</sp-menu-item>
    <sp-menu-item>London</sp-menu-item>
    <sp-menu-item>Maputo</sp-menu-item>
    <sp-menu-item>Melbourne</sp-menu-item>
    <sp-menu-item>New York</sp-menu-item>
    <sp-menu-item>San Francisco</sp-menu-item>
    <sp-menu-item>Santiago</sp-menu-item>
    <sp-menu-item>Tokyo</sp-menu-item>
</sp-picker>

Side (End Aligned)

Use side-aligned="end" to display the <sp-field-label> inline and to align the label text to the "end" of the flow of text:

<sp-field-label
    for="lifestory-2"
    side-aligned="end"
    required
    style="width: 120px"
>
    Life Story
</sp-field-label>
<sp-textfield
    placeholder="Enter your life story"
    id="lifestory-2"
></sp-textfield>
<br />
<br />
<sp-field-label for="birth-place-2" side-aligned="end" style="width: 120px">
    Birthplace
</sp-field-label>
<sp-picker id="birth-place-2">
    <span slot="label">Choose a location:</span>
    <sp-menu-item>Istanbul</sp-menu-item>
    <sp-menu-item>London</sp-menu-item>
    <sp-menu-item>Maputo</sp-menu-item>
    <sp-menu-item>Melbourne</sp-menu-item>
    <sp-menu-item>New York</sp-menu-item>
    <sp-menu-item>San Francisco</sp-menu-item>
    <sp-menu-item>Santiago</sp-menu-item>
    <sp-menu-item>Tokyo</sp-menu-item>
</sp-picker>

Necessity Indicator

Field labels can indicate whether an input is required or optional. By default, required fields are marked with an asterisk icon.

Required (Icon)

<sp-field-label for="name-required" required>Full name</sp-field-label>
<sp-textfield
    placeholder="Enter your full name"
    id="name-required"
    required
></sp-textfield>

Optional (Text)

<sp-field-label for="description-optional">
    Profile description (optional)
</sp-field-label>
<sp-textfield
    placeholder="Enter a description"
    id="description-optional"
></sp-textfield>

States

Disabled

When the associated input field is disabled, the field label should also be disabled.

<sp-field-label for="disabled-field" disabled>Country</sp-field-label>
<sp-textfield
    placeholder="Enter your country"
    id="disabled-field"
    disabled
></sp-textfield>

Behaviors

Text Overflow

When a field label is too long for the available horizontal space, it wraps to form another line.

<sp-field-label for="seminar-field" style="max-width: 200px">
    What you're hoping to learn from the seminar and any specific topics you'd
    like covered
</sp-field-label>
<sp-textfield
    placeholder="Enter your expectations"
    id="seminar-field"
></sp-textfield>

Accessibility

Always include a label

Every input should have a label. An input without a label is ambiguous and not accessible. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be visually hidden but should still include an aria-label in HTML.

Ensure proper association

The for attribute of the field label should match the id attribute of the associated input element to ensure proper association for screen readers and other assistive technologies.

Keep labels concise

Use a short, descriptive label (1-3 words) for the information that users need to provide. Supplementary information or requirements should be shown in help text below the field, not in the label.

Use sentence case

Following Adobe's UX writing style, field labels should be written in sentence case unless they contain words that are branded terms.

Don't add a colon at the end of a field label

The design of the component already communicates the relationship between the label and the input field, so a colon is unnecessary.

Mark only required or only optional fields, not both

In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. This reduces visual noise and makes the form easier to understand.

Changelog

1.8.0 (2025-09-23)

Minor Changes

sp-picker: Fixed escape key behavior in modal overlays containing picker components. Previously, pressing the Escape key when a picker was open inside a modal overlay would not properly close the modal, instead moving focus to the picker. Now, the escape key correctly closes the picker first (if open), then closes the modal overlay on subsequent escape key presses.

This fix adds a check for this.open in the picker's handleEscape method to ensure proper modal overlay closure behavior.

sp-overlay: Added allow-outside-click property to <sp-overlay> with deprecation notice. This property allows clicks outside the overlay to close it, but is not recommended for accessibility reasons and will be removed in a future version.

This property is being added as deprecated to support the fallback for showModal() which was removed as part of performance optimization. We will no longer support outside clicks for modal overlays as they violate accessibility guidelines.

The property defaults to false and shows deprecation warnings when used. Consider using explicit close buttons or modal/page overlay types instead for better accessibility.

sp-menu: Fixed : Fix iPad scrolling issue in picker dropdown where scrolling through menu items would accidentally select the first touched item and close the picker.

The fix implements touch gesture detection to distinguish between scrolling and selection. Added isScrolling getter for public API access. Test on iPad devices with long menus to validate scrolling behavior and selection accuracy.

sp-overlay: Fixed : Added body scroll prevention for modal and page overlays. Overlay automatically blocks body scroll when modal or page overlays are open and restores the original scroll state when they are closed, improving user experience and accessibility for modal dialogs.

sp-clear-button: Clear button styles have been updated to the latest Spectrum CSS version of the clear button. This update includes a major reduction in the number of custom property abstractions needed to support the multiple theming layers (as seen in the styles package).

This update spans the following additional packages:

• @spectrum-web-components/button
• @spectrum-web-components/styles

As the updated styles now offer additional styling options, we have added the following API to the clear button component that exists in the button package:

• quiet - when set to true, the button will be rendered as a quiet button. This is useful for cases where you want to use the clear button in a more subtle way.
• disabled - when set to true, the button will be rendered as a disabled button.
• static-color - currently this only supports the white context color. This is useful for cases where the button appears on a dark background texture. This is a replacement for the previously used variant="overBackground" attribute which is deprecated.

Deprecation

The variant="overBackground" attribute is deprecated; please use the new static-color="white" attribute instead. When this property is used in the component, a deprecation warning will be shown in the console when in debug mode. The variant attribute will be removed in a future release.

sp-card: Fixed the card component's CSS by moving block-size: 100% from the base :host selector to only apply to gallery and quiet variants

sp-overlay: Fixed : external click registration behavior in the sp-overlay component. Programmatic clicks on elements outside of modal overlays now properly register and close the overlay, while user-initiated clicks are prevented from doing so.

sp-card: Enhanced the Card component's checkbox functionality with improved screen reader support and keyboard navigation.

Patch Changes

sp-progress-bar: Added: Deprecation warning for the over-background attribute.

sp-combobox: Replace the use of offsetWidth with a resizeObserver to avoid unecessary, performance-impacting layout reflows.

sp-styles: Bring the CJK font alias token fix from CSS #3883 4e3a120.

The --spectrum-cjk-font token was incorrectly mapped to the code font-family stack instead of --spectrum-cjk-font-family-stack. Thanks @byteakp!

sp-color-wheel: Fixed <sp-color-wheel> step attribute functionality for keyboard navigation. The step attribute now properly controls the increment size when using arrow keys to navigate the color wheel.

sp-switch: ### Fix down state colors for switch

Because the postcss-hover-media-feature plugin converts hover styles into a media query for devices that support hover, the hover styles were overriding any active/down state styles. We needed to target the active/down states of the switch with additional active state selectors, in order to ensure that the active state takes precedence over the hover state, maintaining the correct visual behavior of the switch component across different interaction states.

This fix should address hover + active state discrepancies in S1 and S2 foundations.

sp-contextual-help: Fixed a typo in the default info variant label from "Informations" to "Information".

Additionally, added package dependency for @spectrum-web-components/reactive-controllers@1.7.0.

sp-slider: Editable sliders will now reliably emit input events when interaction starts with the track.

sp-link: Fixed quiet variant links not showing keyboard focus state in Safari. Links with the quiet attribute now properly display focus indicators when navigating with keyboard, improving accessibility for keyboard users.

sp-progress-bar: Smooths the transition animation of indeterminate progress bar by overriding the incoming CSS, and positioning the animating fill element completely off of the progress bar track in both LTR and RTL languages. Before, the fill element was automatically starting on the track which led to a jarring animation loop.

sp-divider: Added: staticColor property to the Divider component, enabling programmatic control of the existing static color functionality.