@spectrum-web-components/coachmark

Overview

<sp-coachmark> is a temporary message that educates users through new or unfamiliar product experiences. They can be chained into a sequence to form a tour.

Usage

yarn add @spectrum-web-components/coachmark

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

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

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

import { Coachmark } from '@spectrum-web-components/coachmark';

Anatomy

The coachmark consists of several key parts:

• A title (via slot="title")
• Content (via slot="content")
• Optional action menu (via slot="actions")
• Optional media content (via slot="asset" or src attribute)
• Navigation controls (via primary-cta and secondary-cta attributes)
• Tour progress indicators (via current-step and total-steps attributes)
• Optional keyboard shortcuts (via modifierKeys and shortcutKey properties)

Here's a complete example showing the anatomy:

<sp-coachmark
    current-step="2"
    total-steps="8"
    open
    primary-cta="Next"
    secondary-cta="Previous"
>
    <!-- Title -->
    <div slot="title">Welcome to the Tour</div>

    <!-- Main content -->
    <div slot="content">
        This coachmark demonstrates the various parts that make up the
        component.
    </div>

    <!-- Media content -->
    <img
        slot="asset"
        src="https://picsum.photos/id/237/200/300"
        alt="Feature demonstration"
    />

    <!-- Action menu -->
    <sp-action-menu
        slot="actions"
        label="More Actions"
        placement="bottom-end"
        quiet
    >
        <sp-menu-item>Skip tour</sp-menu-item>
        <sp-menu-item>Restart tour</sp-menu-item>
    </sp-action-menu>
</sp-coachmark>

Options

Navigation

The primary-cta and secondary-cta attributes are used to display navigation buttons.

<sp-coachmark
    id="coachmark-navigation"
    open
    primary-cta="Next"
    secondary-cta="Previous"
>
    <div slot="title">Coachmark with navigation</div>
    <div slot="content">
        This coachmark demonstrates the navigation buttons.
    </div>
    <!-- Action menu -->
    <sp-action-menu
        slot="actions"
        label="More Actions"
        placement="bottom-end"
        quiet
    >
        <sp-menu-item>Skip tour</sp-menu-item>
        <sp-menu-item>Restart tour</sp-menu-item>
    </sp-action-menu>
</sp-coachmark>

Progress Indicator

The current-step and total-steps attributes are used to display a progress indicator.

<sp-coachmark
    id="coachmark-progress"
    open
    current-step="2"
    total-steps="8"
    primary-cta="Next"
    secondary-cta="Previous"
>
    <div slot="title">Coachmark with progress indicator</div>
    <div slot="content">
        This coachmark demonstrates the progress indicator.
    </div>
    <!-- Action menu -->
    <sp-action-menu
        slot="actions"
        label="More Actions"
        placement="bottom-end"
        quiet
    >
        <sp-menu-item>Skip tour</sp-menu-item>
        <sp-menu-item>Restart tour</sp-menu-item>
    </sp-action-menu>
</sp-coachmark>

Keyboard Shortcuts

The shortcut-key is the primary key used to trigger an interaction and are typically an alphanumeric value (and thus will be rendered as an uppercase character).

<sp-coachmark
    open
    current-step="2"
    total-steps="8"
    primary-cta="Next"
    secondary-cta="Previous"
    shortcut-key="⌘"
>
    <div slot="title">Shortcut Key</div>
    <div slot="content">This coachmark demonstrates the shortcut key.</div>

    <!-- Action menu -->
    <sp-action-menu
        slot="actions"
        label="More Actions"
        placement="bottom-end"
        quiet
    >
        <sp-menu-item>Skip tour</sp-menu-item>
        <sp-menu-item>Restart tour</sp-menu-item>
    </sp-action-menu>
</sp-coachmark>

Modifier Keys

The modifierKeys is an array of modifier keys used to trigger an interaction. This is not an attribute, but a property so we need to set it via JavaScript.

<sp-coachmark
    open
    current-step="2"
    total-steps="8"
    primary-cta="Next"
    secondary-cta="Previous"
    id="coachmark-keys"
>
    <div slot="title">Coachmark with modifier keys</div>
    <div slot="content">This coachmark demonstrates the modifier keys.</div>
    <!-- Action menu -->
    <sp-action-menu
        slot="actions"
        label="More Actions"
        placement="bottom-end"
        quiet
    >
        <sp-menu-item>Skip tour</sp-menu-item>
        <sp-menu-item>Restart tour</sp-menu-item>
    </sp-action-menu>
</sp-coachmark>
<script type="module">
    const initCoachMark = () => {
        const coachmark = document.querySelector('#coachmark-keys');
        const modifierKeys = ['⇧ Shift', '⌘'];
        coachmark.modifierKeys = modifierKeys;
    };
    customElements.whenDefined('code-example').then(() => {
        customElements.whenDefined('sp-coachmark').then(() => {
            initCoachMark();
        });
    });
</script>

Behaviours

User action-dependent coachmarks are designed to guide users based on their interactions within your application. In such cases, there is no "Next Step" button, as the coachmark progresses when the user takes a specific action. This allows users to learn by doing, rather than simply reading instructions. The coachmark remains until the user performs the required action or takes an alternative route in the tour, such as skipping, restarting, or moving back to a previous step.

Inside the <sp-coachmark>, add the content and instructions for the coachmark in the <sp-coachmark>. You can also define primary and secondary CTA buttons for user interaction.

<sp-coachmark
    id="coachmark-action"
    open
    current-step="2"
    total-steps="8"
    primary-cta="Asset added"
    secondary-cta="Previous"
>
    <div slot="title">Coachmark with user action</div>
    <div slot="content">
        This coachmark waits for the user to complete a specific action.
    </div>
    <sp-action-menu
        label="More Actions"
        placement="bottom-end"
        quiet
        slot="actions"
    >
        <sp-menu-item>Skip tour</sp-menu-item>
        <sp-menu-item>Restart tour</sp-menu-item>
    </sp-action-menu>
</sp-coachmark>

Accessibility

Coachmarks should be designed with accessibility in mind:

• Always provide clear, concise title and content text
• Use descriptive labels for navigation buttons
• Ensure keyboard navigation works for multi-step tours
• Make sure images have appropriate alt text
• Consider focus management during tour progression

For users that rely on screen readers, coachmarks announce their presence and content appropriately. The component manages focus to ensure users can navigate through the tour using only a keyboard.

Changelog

1.9.0 (2025-10-13)

Minor Changes

sp-icons-workflow: - Upgraded to @adobe/spectrum-css-workflow-icons@5.0.0. - Includes changes from previous a4u upstream releases: - Added S2_Icon_HeartFilled_20_N.svg, updated S2_Icon_SpeedFast_20_N.svg. - Replaced all 22×20px Cloud State icons with 20px variants. - Removed deprecated multi-colored error icon. Added new Cloud State icons (Disconnected, Error, InProgress, Online, Paused, Pending, SlowConnection). - Updated several other icons (CloseCaptions, CommentHide, Community, etc.).

• For the full changelog, see: https://github.com/adobe/spectrum-css-workflow-icons/pull/50

Patch Changes

sp-button: - Fixed: Aria-label handling in <sp-button> component.

• Fixed: Moved aria-label updates to occur after slot content changes are processed to prevent timing issues
• Added: Enhanced label property support for programmatic aria-label control
• Added: Comprehensive tests for aria-label behavior during content and pending state changes
• Fixed: Removed duplicate aria-label update logic in update() method

These changes ensure that aria-labels are properly managed and preserved across component state changes, improving accessibility for screen reader users.

sp-combobox: - Fixed: Pending state handling and accessibility in <sp-combobox> component.

• Changed: Removed dependency on PendingStateController and implemented inline pending state handling
• Fixed: Updated aria-labelledby attribute ordering to improve screen reader experience (label applied-label pending-label)
• Fixed: Updated progress circle implementation to use role="presentation" instead of aria-valuetext
• Added: Direct pending state visual rendering with improved accessibility

These changes improve accessibility for pending states while reducing unnecessary component dependencies.

sp-menu: - Fixed: MenuItem focus stealing from input elements on mouseover by enhancing MenuItem's handleMouseover method to detect when an input element currently has focus and prevent stealing focus in those cases.

sp-alert-dialog: - Fixed: Make the divider color transparent only for Spectrum 2 theme

sp-picker: - Fixed: Picker border color should be hidden in S2 theme

sp-textfield: - Fixed: Update border radius and border width for different t-shirt sizes for textfield component for S2 and Express themes

sp-textfield: - Fixed: Update border color and block padding inside the textfield and textarea components for S2 and Express themes

sp-picker: - Fixed: Pending state handling and accessibility in <sp-picker> component.

• Changed: Removed dependency on PendingStateController and implemented inline pending state handling
• Fixed: Updated aria-labelledby attribute ordering to improve screen reader experience (icon label applied-label pending-label)
• Fixed: Updated progress circle implementation to use role="presentation" instead of aria-valuetext
• Added: Direct pending state visual rendering with improved accessibility

These changes improve accessibility for pending states while reducing unnecessary component dependencies.

sp-progress-circle: - Fixed: Accessibility warning logic in <sp-progress-circle> component.

• Fixed: Updated accessibility warning logic to only apply when role="progressbar" is explicitly set
• Fixed: Improved label validation for better accessibility compliance

These changes ensure accessibility warnings are only shown when appropriate and improve overall accessibility compliance.

sp-reactive-controllers: - Fixed: Accessibility and caching in PendingStateController.

• Fixed: Updated progress circle to use role="presentation" for better accessibility compliance
• Fixed: Improved aria-label caching logic to better handle dynamic label changes
• Added: Documentation noting the controller is primarily used by <sp-button> component
• Fixed: Enhanced caching mechanism to preserve user-set aria-labels during pending states

These changes improve accessibility compliance and aria-label management for components using the pending state controller.

sp-help-text: - Fixed: Update block paddings for S2 and Express themes

sp-field-label: - Fixed: Update block paddings for S2 and Express themes