There are several options how to install Blobity to your site.

The first is to include Blobity with scripts tag from the downloaded version available in this repository. This version will create a global Blobity object which you can use to create your instance.

<script src="./dist/blobity.min.js"></script>

The second is to include the same script from CDN. The CDN version of Blobity also includes something called autostart, which will initialize Blobity with the default options.

<script src="https://cdn.blobity.dev/by.js?licenseKey=..."></script>

You can prevent that by adding noAutoStart parameter to the src URL.

<script src="https://cdn.blobity.dev/by.js?noAutoStart&licenseKey=..."></script>

The third and most flexible option is to install with package managers like npm or yarn.

npm install blobity --save
# or 
yarn add blobity

Once the package is installed as a node module (eg. inside of node_modules folder), you can access it from blobity path.

import Blobity from 'blobity';

There is an advantage to the latest format, because the library is not bundled, doesn't contain boiler plate code of the bundler, doesn't pollute the global scope and is much smaller and can be effectively tree-shaked as well. The package also contains additional utils for React for example.

To start Blobity, the instance needs to be created from its class. The class is either defined globally from a standalone versions, or can be imported from a package as a default export.

const options = { color: 'rgb(180, 180, 180)' };
new Blobity(options);

// or if imported from package
import Blobity from 'blobity';

const options = { color: 'rgb(180, 180, 180)' };
new Blobity(options);

As you may have noticed in a previous example, Blobity accepts options as an argument when the instance is being created. Options are passed as an object.

const blobity = new Blobity({ option: "value" });

Blobity also allows to change options on the go with updateOptions method. This will only overwrite the defined subset of options and won't affect any options that are not passed in the method parameter object.

const blobity = new Blobity({ option: "value" });
blobity.updateOptions({ option: "newValue" });

Following is a table of all available options, together with the description and default value.

Some of the options can be also overwritten for specific elements, with data-blobity-[option] HTML attribute, the same way as the text for tooltip is defined. The following is an example of the usage.

<div data-blobity-tooltip="Tooltip text">I will have a tooltip with "Tooltip text" text.</div>
<div data-blobity-offset-x="10">I will have a X offset (option focusableElementsOffsetX) of 10 regardless of the global Blobity option.</div>
<div data-blobity-offset-y="10">I will have a Y offset (option focusableElementsOffsetY) of 10 regardless of the global Blobity option.</div>
<div data-blobity-magnetic="false">I will have magnetic behaviour (option magnetic) disabled regardless of the global Blobity option.</div>
<div data-blobity-radius="10">I will have a radius of the blob square (option radius) of 10 regardless of the global Blobity option.</div>
<div data-no-blobity>If the focusableElements options wasn't changed form defualt value, I will not be considered focusable element.</div>

Blobity can display a tooltip when hovered over a focusable element instead of highlighting it visually. THis can be achieved with data-blobity-tooltip HTML attribute, together with the text it should contain. This is mostly meant for short texts.

<div data-blobity-tooltip="Tooltip text">I will have a tooltip with "Tooltip text" text.</div>

Blobity has a several additional public API methods that can be used to control it programmatically.

focusElement method accepts a DOM element and force highlights a specific element on the page regardless of the mouse position. It's useful when an attention needs to be drawn to a specific place.

const blobity = new Blobity();
const element = document.getElementById('some-important-button');

blobity.focusElement(element);

showTooltip method accepts a string and force shows a tooltip with said test on the page regardless of the mouse position. It's useful when you want to communicate some quick instructions programmatically.

const blobity = new Blobity();
const tooltip = 'Hey there!';

blobity.showTooltip(tooltip);

reset method disables the effects of the focusElement and showTooltip methods described previously.

const blobity = new Blobity();

blobity.reset();

Since Blobity is a global library for which the instances should be created once, there is a helper hook to make initialization of Blobity easier in React applications. This hook can be imported from the package version of Blobity. It accepts the same options as Blobity does, and returns a React ref of the instance.

import useBlobity from 'blobity/lib/useBlobity';

const Component = () => {
    const blobity = useBlobity({
        licenseKey: '...'
    });

    return <div />;
};

Please, check the LICENSE.md file in the root of this repository tree.

Any contributions are welcome!

Remember, if merged, your code will be used as part of a commercial product if merged. By submitting a Pull Request, you are giving your consent for your code to be integrated into Blobity as part of a commercial product.