sp-coachmark

NPM 1.7.0

View Storybook

Try it on Stackblitz
Overview API Changelog

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

See it on NPM! How big is this package in your project? Try it on Stackblitz

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.

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/asset@1.7.0
    • @spectrum-web-components/button@1.7.0
    • @spectrum-web-components/button-group@1.7.0
    • @spectrum-web-components/icon@1.7.0
    • @spectrum-web-components/icons-ui@1.7.0
    • @spectrum-web-components/base@1.7.0
    • @spectrum-web-components/reactive-controllers@1.7.0
    • @spectrum-web-components/shared@1.7.0

1.6.0

Patch Changes

  • Updated dependencies [00eb0a8]:
    • @spectrum-web-components/button@1.6.0
    • @spectrum-web-components/button-group@1.6.0
    • @spectrum-web-components/asset@1.6.0
    • @spectrum-web-components/icon@1.6.0
    • @spectrum-web-components/icons-ui@1.6.0
    • @spectrum-web-components/base@1.6.0
    • @spectrum-web-components/reactive-controllers@1.6.0
    • @spectrum-web-components/shared@1.6.0

1.5.0

Patch Changes

  • Updated dependencies [165a904, 4e06533]:
    • @spectrum-web-components/asset@1.5.0
    • @spectrum-web-components/button-group@1.5.0
    • @spectrum-web-components/button@1.5.0
    • @spectrum-web-components/icon@1.5.0
    • @spectrum-web-components/icons-ui@1.5.0
    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/reactive-controllers@1.5.0
    • @spectrum-web-components/shared@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/asset@1.4.0
    • @spectrum-web-components/button@1.4.0
    • @spectrum-web-components/button-group@1.4.0
    • @spectrum-web-components/icon@1.4.0
    • @spectrum-web-components/icons-ui@1.4.0
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/reactive-controllers@1.4.0
    • @spectrum-web-components/shared@1.4.0

1.3.0

Patch Changes

  • Updated dependencies [ea38ef0]:
    • @spectrum-web-components/reactive-controllers@1.3.0
    • @spectrum-web-components/button@1.3.0
    • @spectrum-web-components/button-group@1.3.0
    • @spectrum-web-components/asset@1.3.0
    • @spectrum-web-components/icon@1.3.0
    • @spectrum-web-components/icons-ui@1.3.0
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/shared@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Features

  • reactive-controllers: Migrate to Colorjs from Tinycolor (#4713) (9d740f0)

1.1.2 (2025-02-12)

Note: Version bump only for package @spectrum-web-components/coachmark

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/coachmark

1.1.0 (2025-01-29)

Bug Fixes

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

Features

  • add an optional chromatic vrt action (7d2f840)

1.0.3 (2024-12-09)

Note: Version bump only for package @spectrum-web-components/coachmark

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/coachmark

1.0.0 (2024-10-31)

BREAKING CHANGES

  • remove 'variant' and 'static' attributes from coach-indicator (#4772)

0.49.0 (2024-10-15)

Features

  • add static-color to replace static (#4808) (43cf086)

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/coachmark

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/coachmark

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/coachmark

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/coachmark

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/coachmark

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/coachmark

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/coachmark

0.44.0 (2024-07-15)

0.43.0 (2024-06-11)

0.42.5 (2024-05-24)

Bug Fixes

  • coachmark,overlay: adjust imports of overlay and coachmark (#4455) (39706da)

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/coachmark

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/coachmark

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/coachmark

0.42.1 (2024-04-02)

Bug Fixes

  • coachmark: add "step-count" slot for custom/internationalized pagination content (#4215) (f4136a6)

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/coachmark

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/coachmark

0.41.0 (2024-02-13)

Features

  • coachmark: rename "sp-coachmark" to "sp-coachmark-indicator", add "sp-coachmark" (#3639) (a94389c)

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/coachmark

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/coachmark

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/coachmark

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/coachmark

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/coachmark

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/coachmark

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/coachmark

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/coachmark

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/coachmark

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/coachmark

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/coachmark

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/coachmark

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/coachmark

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/coachmark

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/coachmark

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/coachmark

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/coachmark

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/coachmark

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/coachmark

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/coachmark

0.30.0 (2023-05-03)

Bug Fixes

  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • update side effect listings (8160d3a)
  • update to latest spectrum-css packages (a5ca19f)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • coachmark: add coachmark pattern (f53ae70)
  • coachmark: update spectrum css input (a099ee6)
  • include all Dev Mode files in side effects (f70817c)
  • leverage "exports" field in package.json (321abd7)
  • leverage latest Spectrum button API (9faeade)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • use latest exports specification (a7ecf4b)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

0.10.9 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/coachmark

0.10.8 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/coachmark

0.10.7 (2023-03-22)

Note: Version bump only for package @spectrum-web-components/coachmark

0.10.6 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/coachmark

0.10.5 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/coachmark

0.10.4 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/coachmark

0.10.3 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/coachmark

0.10.2 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/coachmark

0.10.1 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/coachmark

0.10.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.9.8 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/coachmark

0.9.7 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/coachmark

0.9.6 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/coachmark

0.9.5 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/coachmark

0.9.4 (2022-05-27)

Note: Version bump only for package @spectrum-web-components/coachmark

0.9.3 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/coachmark

0.9.2 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/coachmark

0.9.1 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/coachmark

0.9.0 (2022-03-04)

Features

  • leverage latest Spectrum button API (9faeade)

0.8.3 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/coachmark

0.8.2 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/coachmark

0.8.1 (2021-12-13)

Note: Version bump only for package @spectrum-web-components/coachmark

0.8.0 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/coachmark

0.7.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/coachmark

0.7.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.6.8 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/coachmark

0.6.7 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/coachmark

0.6.6 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/coachmark

0.6.5 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/coachmark

0.6.4 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/coachmark

0.6.3 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/coachmark

0.6.2 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/coachmark

0.6.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/coachmark

0.6.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.5.1 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

0.5.0 (2021-01-21)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • coachmark: update spectrum css input (a099ee6)

0.4.0 (2021-01-13)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • coachmark: update spectrum css input (a099ee6)

0.3.3 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/coachmark

0.3.2 (2020-10-12)

Bug Fixes

  • include default export in the "exports" fields (f32407d)

0.3.1 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.3.0 (2020-08-31)

Features

  • update to Spectrum CSS v3.0.0 (e8b3d8f)

0.2.1 (2020-08-19)

Note: Version bump only for package @spectrum-web-components/coachmark

0.2.0 (2020-07-17)

Features

  • leverage "exports" field in package.json (321abd7)

0.1.2 (2020-06-08)

Note: Version bump only for package @spectrum-web-components/coachmark

0.1.1 (2020-04-16)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

0.1.0 (2020-04-07)

Features

  • coachmark: add coachmark pattern (f53ae70)

Attributes and Properties

Property Attribute Type Default Description asset asset 'file' | 'folder' | undefined currentStep current-step number | undefined hasAsset has-asset boolean false item item CoachmarkItem | undefined modifierKeys modifierKeys string[] | undefined [] open open boolean false Whether the popover is visible or not. placement placement "top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end" 'right' tip tip boolean false totalSteps total-steps number | undefined

Slots

Name Description actions an `sp-action-menu` element outlining actions to take on the represened object cover-photo This is the cover photo for Default and Quiet Coachmark description A description of the card heading HTML content to be listed as the heading step-count Override the default pagination delivery with your own internationalized content default slot content to display within the Popover

Events

Name Type Description primary Event Announces that the "primary" button has been clicked. secondary Event Announces that the "secondary" button has been clicked.