A programmatic way of making highlight guide π
- CodePen - https://codepen.io/ranndev/pen/oNgvwQV
# 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.
There are 2 required styles that must be included into your app.
- 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. - 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.
If you're going to import the package using <script>
tag, use UMD (Universal Module Definition).
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>'; } }, }, });
UIGuide.highlight('#target-element', (highlighted) => { highlighted.unhighlight(); }); // or UIGuide.clear();
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, });
Popper.js - For making our UIGuide's popup so incredible π
This project is licensed under the MIT License - see the LICENSE file for details.