Skip to main content

Coachmarks

Installation#

For detailed instructions, view our install section in this documentation. Make sure all of the dependencies and polyfills are loaded to make the component cross-browser compatible.

CDN#

<script src="https://unpkg.com/@pearson-ux/coachmark"></script>

NPM#

npm i @pearson-ux/coachmark --save

Demo#

Important note The component markup is not hard coded, instead its built on the fly when the trigger button is clicked. To make this happen, you will need to build your own script to trigger these coachmarks. You can see how we put everything together below, in our structure section.

Default Coachmark#

<pearson-coachmark
position="top"
trigger="#openDefault"
reference="#defaultRef"
title="Default Coachmark"
content="Content for your enjoyment"
type="default"
arrow="true"
gotit="Got it">
</pearson-coachmark>

Generic Coachmark#

<pearson-coachmark type="generic">
<!-- content markup -->
</pearson-coachmark>

Informational Coachmark#

<pearson-coachmark type="informational">
<!-- content markup -->
</pearson-coachmark>

Joyride#

Structure#

The recommended way to fire off a coachmark is to generate the markup with JS, and not place a hardcoded <pearson-coachmark> tag in the document.

First, we'll create a button element that triggers the alert script.

In this example well create a basic button with the id you want to query in your script. Well use #openCoachmark

Make sure you add the attribute ```aria-haspopup="dialog"``` to the button.
<button id="openDefault" class="gr-btn">Trigger Coachmark</button>

Next we will build out the script that generates the coachmark.

We start the script by querying the button that triggers the coachmark.

const trigger = document.querySelector('#openDefault');

Next, we create a <pearson-coachmark> element and assign it to variable.

const coachmark = document.createElement('pearson-coachmark');

Then we'll add one more variable called target where we want the coachmark to appear in the dom.

We recommended that coachmark is loaded after a MAIN dom element, outside the applications markup
const target = document.querySelector('#main');

Now, we'll create a function that builds out and renders the coachmark element.

function generateCoach(opts) {
for (let attrName in opts) {
coachmark.setAttribute(attrName, opts[attrName])
}
target.appendChild(coachmark)
}

Then lets use that function to generate your coachmark.

const coachMark = function (event) {
generateCoach({
position: 'top',
trigger: '#openDefault',
reference: '#openDefault',
title: 'Default Coachmark',
content: 'Content for your enjoyment',
type: 'default',
arrow: true,
gotIt: "Got it",
dismiss: true
});
};

Finally, lets add an event listener to the button that triggers the coachmark.

if (trigger !== null) {
trigger.addEventListener('click', function (event) {
coachMark();
event.stopImmediatePropagation()
});
}

Last but not least, add the script to your document.

Important note: To view the full script we used in these demos you can view it on GitHub.

API#

Required#

All these attributes are required.

AttributeTypeDefaultDescription
positionStringunsettop right bottom left Each placement can have a variation from -start -end
triggerStringunsetThe ID of the button invoking the coachmark, this is important for accessibility and focus management.
referenceStringunsetThe ID of element you want the coachmark to appear on.
titleStringunsetThe title of the coachmark
contentStringunsetThe content you want the coachmark to display
typeStringdefaultThe type of coachmark default informational generic

Optional#

All these attributes are optional.

AttributeTypeDefaultDescription
arrowBoolunsetRenders an arrow on the coachmark.
gotitStringunsetIf left blank gotit=' ', the coachmark will render an optional got it button. If a value is specified e.g.gotit='next coachmark the coachmark will render a button with the label 'next coachmark'
dismissBoolunsetIf set to true, the got it button will also dismiss the coachmark
openBoolTRUEremoving this attribute will destroy the coachmark and fire off a dismiss event.

Events#

pearson-coachmark emits two events: dismiss and proceed Once an coachmark is dismissed, it is removed from the DOM.

EventDescription
dismissWill fire when the user interacts with the close button.
proceedWill fire when the user interacts with the 'got it' button and the dismiss attribute is not specified.
const coachMarkNode = document.querySelector('pearson-coachmark')
coachMarkNode.addEventListener('dismiss', function (e) {
// Do something when the close button is clicked
});
coachMarkNode.addEventListener('proceed', function (e) {
// Do something when the got it button is clicked
});

HTML Markup#

Do you want to use your own JS to make the coachmarks function? No problem, use the markup below along with CSS to build coachmarks with your own JS.

Important note: You can follow the UXF guidelines to view the suggested functionality of the coachmark.

Here are some basic practices to make sure the coachmarks you build are accessible.
<div role="dialog" aria-labelledby="coachmark-title" aria-describedby="coachmark-body" class="gr-coachmark-container">
<div class="coachmark">
<div class="content">
<div class="title-container">
<h3 id="coachmark-title">Ready to invite students?</h3>
<button class="gr-btn icon-btn-18" aria-label="Close, Ready to invite students?">
<svg focusable="false" class="icon-18" aria-hidden="true">
<use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#close-18"></use>
</svg>
</button>
</div>
<p id="coachmark-body">
Open the course menu to access invite instructions.
</p>
<button id="gotIt" class="coach-link" href="#" aria-label="Got It">Got it</button>
</div>
</div>
<div class="popper__arrow" x-arrow></div>
</div>