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.

Attribute	Type	Default	Description
position	String	unset	top right bottom left Each placement can have a variation from -start -end
trigger	String	unset	The ID of the button invoking the coachmark, this is important for accessibility and focus management.
reference	String	unset	The ID of element you want the coachmark to appear on.
title	String	unset	The title of the coachmark
content	String	unset	The content you want the coachmark to display
type	String	default	The type of coachmark default informational generic

Optional

All these attributes are optional.

Attribute	Type	Default	Description
arrow	Bool	unset	Renders an arrow on the coachmark.
gotit	String	unset	If 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'
dismiss	Bool	unset	If set to true, the got it button will also dismiss the coachmark
open	Bool	TRUE	removing 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.

Event	Description
dismiss	Will fire when the user interacts with the close button.
proceed	Will 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>