sp-coachmark
NPM
1.0.1
Storybook
View Storybook
Try it on
webcomponents.dev
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 replacestatic
(#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 #
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
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 #
actions
cover-photo
description
heading
step-count
default slot
Events #
primary
Event
Announces that the "primary" button has been clicked.
secondary
Event
Announces that the "secondary" button has been clicked.
Description #
<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';
Example #
Default #
<sp-coachmark open> <div slot="title">Coachmark with Text Only</div> <div slot="content"> This is a Coachmark with nothing but text in it. Kind of lonely in here. </div> </sp-coachmark>
Using Action Menu #
Coach marks can include an <sp-action-menu>
, which appears at the top right of the coach mark. The <sp-action-menu>
should only include ways to interact with the coach mark tour as a whole, with options like “Skip tour” or “Restart tour.”
<sp-coachmark open current-step="2" total-steps="8" primary-cta="Next" secondary-cta="Previous" > <div slot="title">Coachmark with Text Only</div> <div slot="content"> This is a Coachmark with nothing but text in it. Kind of lonely in here. </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>
User Action Dependent #
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.
Event Handling:
The primary and secondary CTA buttons within the coachmark popover can be configured to dispatch events when clicked.
<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 is a Coachmark with nothing but text in it. Kind of lonely in here. </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> <script type="module"> const initCoachMark = () => { const coachmark = document.querySelector('#coachmark-action'); coachmark.addEventListener('primary', () => console.log('primary call to action')); coachmark.addEventListener('secondary', () => console.log('secondary call to action')); }; customElements.whenDefined('sp-coachmark').then(() => { initCoachMark(); }); </script>
Using Images, GIFs #
Coach marks can contain images or videos that relate to their content, such as demonstrations of gestures, the feature being used, or illustrations. To use these kinds of media in your rich tooltip, specify a src
, the type of media, either by using the string or media-type
object, and an optional imageAlt
text describing the content.
Media Types allowed: Images & Gifs
Image #
<sp-coachmark current-step="2" total-steps="8" open primary-cta="Next" secondary-cta="Previous" src="https://picsum.photos/id/237/200/300" media-type="image" > <div slot="title">Coachmark with 16:9 image</div> <div slot="content">This is a Coachmark with some description</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>
Custom Image/Gif #
A custom media can also be added via <slot name="cover-photo"></slot>
<sp-coachmark current-step="2" total-steps="8" open primary-cta="Next" secondary-cta="Previous" > <div slot="title">Coachmark with 16:9 image</div> <div slot="content">This is a Coachmark with some description</div> <img slot="asset" src="https://picsum.photos/id/237/200/300" alt="" /> <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>
Shortcut keys and modifier keys #
Shortcut keys and modifier keys are ways to show users how to trigger a particular tool.
The shortcutKey
is the primary key used to trigger an interaction and are typically an alphanumeric value (and thus will be rendered as an uppercase character), while the modifierKeys
are an array of string
s that represent alternate keys that can be pressed, like Shift
, Alt
, Cmd
, etc.
<sp-coachmark open current-step="2" total-steps="8" primary-cta="Next" secondary-cta="Previous" id="coachmark-keys" > <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> <script type="module"> const initCoachMark = () => { const coachmark = document.querySelector('#coachmark-keys'); const modifierKeys = ['⇧ Shift', '⌘']; const content = { title: 'I am a Coachmark with keys', description: 'This is a Coachmark with nothing but text in it.' }; coachmark.content= content coachmark.modifierKeys = modifierKeys }; customElements.whenDefined('code-example').then(() => { customElements.whenDefined('sp-coachmark').then(() => { initCoachMark(); }); }); </script>