DOCUMENTATION.md

Documentation

Here you will find the documentation describing how to use zeroclick.

Summary

1. How it works
2. Install
3. Properties
4. Methods
5. Events

How it works

This plugin simulate a user click through the MouseEvent API: the default event is prevented and called later, when the timeout time has elapsed or your custom Promise resolved.

Be sure to read the disclaimer notice.

Install

Want to try zeroclick? Let’s install it!

Use with a bundler

Zeroclick is published on the NPM registry and GPR registry, so you can install it through the command line interpreter using your favorite package manager. This is the best way to install the library if you are comfortable with javascript bundlers like webpack or rollup.

# npm
npm install @studiomotio/zeroclick

# yarn
yarn add @studiomotio/zeroclick

Then import it like any other module inside your build:

import zeroclick from '@studiomotio/zeroclick';

zeroclick.init({
  // ...
});

Using a bundler has many advantages like output compression, code splitting, tree shaking, etc., so we encourage you to use this kind of tool with zeroclick.

Use with a CDN

To rapidly include the minified production file in your webpage, load the latest build from your favorite CDN using a generic script markup:

<!-- unpkg -->
<script src="https://unpkg.com/@studiomotio/zeroclick"></script>

<!-- jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/@studiomotio/zeroclick"></script>

Then init zeroclick:

<script>
  zeroclick.init({
    // ...
  });
</script>

By default, if no one is specified, the CDN will automatically target the @latest version of zeroclick and load the UMD build from dist/zeroclick.umd.js.

Other setup

Zeroclick is build upon microbundle and is provided with an ESM and Modern version include in the package dist folder.

Properties

API reference that describe plugin properties.

on

Type: String | NodeList Default: a

Define on which elements the plugin is applied. You can update this list at any time inside your application using the refresh method.

zeroclick.init({
  on: document.querySelector('a.zeroclick')
});

If you provide a String, it will automatically use querySelectorAll to create a NodeList.

timeout

Type: Number Default: 600

The time before the click event is dispatched on the hovered link.

zeroclick.init({
  timeout: 700
});

This property will be ignored when using a custom Promise through await.

preventClick

Type: Boolean Default: true

Prevent the user to click on eligible links: this allow a full "zero click" experience.

Note that when the keyboard Enter key is pressed, the browser call the link click event, using a MouseEvent instead of a KeyboardEvent, which make the event source difficult to detect. This behavior is managed by the plugin using the keydown event and allow you to prevent the user mouse click through preventClick without blocking keyboard usage, needed to maintain page accessibility.

await

Type: Promise Default: undefined

Define a custom Promise that need to be resolved in order to dispatch the link click event, or cancel it if the Promise is rejected. This allow you to do some cool stuff before going to the next page: like playing an animation, fetching some content, etc..

zeroclick.init({
  await: (resolve, reject) => {
    new customAnimation({
      onComplete: () => {
        resolve();
      },
      onFailure: () => {
        reject();
      }
    });
  }
});

Note that rejecting the Promise will prevent onCancel event to be called.

Methods

API reference that describe plugin methods.

init(options)

Type: Function

The main method that initialize the plugin, with or without custom options. This make zeroclick up and running on elements you provide in the on property.

zeroclick.init({
  // options here
});

refresh()

Type: Function

Refresh the internal NodeList in order to add new eligible links from the DOM. This is useful when your site is running like a SPA (Single Page Application), with Vue, React, etc..

zeroclick.refresh();

destroy()

Type: Function

This remove all event listeners from eligible links, making the plugin inactive.

zeroclick.destroy();

Events

The "click process" is split into three states:

Name	Description
engage	you place the mouse cursor hover the link
dispatch	the event is dispatched on the link (user MouseEvent click simulation)
cancel	you remove the mouse cursor from the link before the event is dispatched

All of this states are declined into custom events, callbacks and data attributes.

Custom events

You can add an event listener on a specific link using:

document.querySelector('.my-link').addEventListener('dispatch', (e) => {
  // do something when the click event is dispatched on .my-link
});

Callbacks

You can call specific code globally using callbacks:

zeroclick.init({
  onDispatch: () => {
    // do something when a link click event is dispatched
  }
});

Data attributes

In addition, the plugin provide a bunch of data-attributes, to easily add custom styles/scripts in your application.

• data-zeroclick="engage"
• data-zeroclick="dispatch"
• data-zeroclick="cancel"