Skip to content
This repository was archived by the owner on Sep 9, 2020. It is now read-only.

ranndev/ui-guide

UIGuide

A programmatic way of making highlight guide πŸ”†

Build Status Greenkeeper Status codecov - Code Coverage Synk - Vulnerabilities CodeFactor - Grade

Examples

Installation

# Using npm npm install @ranndev/ui-guide --save
# Using Yarn yarn add @ranndev/ui-guide

Note: Popper.js is a peer dependency of this package. Make sure to install it too.

Setup

Styles

There are 2 required styles that must be included into your app.

  1. Base style - Includes the base styles for UIGuide elements. This is located from /dist/css/ui-guide(.min).css or /dist/scss/ui-guide.scss if you're using Scss.
  2. Theme style - Includes the styles that gives color and animation to UIGuide elements. This is located from /dist/css/themes/* or /dist/scss/themes/* if you're using Scss.

Scripts

If you're going to import the package using <script> tag, use UMD (Universal Module Definition).

Usage

Highlight element

Basic highlighting.

UIGuide.highlight('#target-element'); // or const target = document.querySelector('#target-element'); UIGuide.highlight(target);

Highlight after highlight.

UIGuide.highlight('#get-started-button').then((highlighted) => { highlighted.element.onclick = () => { UIGuide.highlight('#second-step-button').then(() => { // ... }); }; });

Using async ... await

async function startDemo() { const highligted1 = await UIGuide.highlight('#get-started-button'); highlighted1.element.onclick = async () => { const highligted2 = await UIGuide.highlight('#second-step-button'); // ... }; }

Highlight with popup

UIGuide.highlight({ element: '#target-element', events: { onElementsReady: (elements) => { if (elements.popup) { // Do whatever you want to popup element elements.popup.innerHTML = '<p>Click Me!</p>'; } }, }, });

Unhighlight

UIGuide.highlight('#target-element', (highlighted) => { highlighted.unhighlight(); }); // or UIGuide.clear();

Configure

Configuring the global settings.

Note: All the configuration properties in the code snippet below are optional.

UIGuide.configure({ // Option on wether the target element should be clickable. true by default. clickable: true, // Automatically set the focus on the target element. Enabled by default. autofocus: true, // If `false`, It will throw an error immediately once searching for the // target element fail on the first try. wait: { // A delay (in milliseconds) before it will try to search for the target // element again. Default value is 150. delay: 150, // A maximum wait time before it give up on searching for the target element. // An error will be thrown when the set 'max' reached. Default value is Infinity max: Infinity, }, // If true, a popup will show using the default popper.js options. It can // also be a popper options, which will use to override the // default popper options (https://popper.js.org/popper-documentation.html#Popper.Defaults). popper: true, // When this is set to 'highlight-box', the highlight's element // ('[uig-highlight-box]') will be used as the popper reference element. // It will be the highlighted element otherwise. popperRef: 'highlight-target', // Options for listening on events. events: { // This event will fire once the target element successfully queried. onTargetFound: (target) => {}, // This will fire when the target, highlight, and popup (if available) // elements are ready. onElementsReady: (elements) => {}, // This will fire everytime the highlight's element request an update. // Important! Listening on this event will bring you the full // responsibility of updating the highlight & popup elements. Make sure to // implement this function as performant as possible. onHighlightUpdate: (elements) => {}, }, // Overrides the update delay for the highlight element. // By default, the position and size of highlight element were updated every // 0 miliseconds. highlightUpdateDelay: 0, });

Credits

Popper.js - For making our UIGuide's popup so incredible πŸŽ‰

License

This project is licensed under the MIT License - see the LICENSE file for details.

About

A programmatic way of making highlight guide πŸ”†

Topics

Resources

License

Code of conduct

Contributing

Stars

Watchers

Forks

Packages