repository·master·Indexed 21 days ago
https://github.com/gmrchk/blobityA library for creating a visual blob cursor effect on websites. It supports vanilla JavaScript, React, and Vue, and can be integrated via CDN, script tags, or npm. Features include dynamic configuration via updateOptions, programmatic control through methods like focusElement, showTooltip, and bounce, and granular element overrides using HTML data attributes. Version 0.2.4.
prefers-reduced-motion CSS media feature. If a user has enabled reduced motion in their system settings, Blobity will reduce animations where possible without significantly impacting the design.You can display a tooltip when a user hovers over a focusable element by adding the data-blobity-tooltip attribute to the HTML element. The value of the attribute will be the text displayed in the tooltip. This is intended for short text snippets.
<div data-blobity-tooltip="Tooltip text">I will have a tooltip with "Tooltip text" text.</div>You can override global Blobity settings for specific HTML elements using data-blobity-[option] attributes. This allows for granular control over individual elements without changing the global instance configuration.
Supported overrides include:
data-blobity-tooltip: Sets the text for the tooltip.data-blobity-offset-x: Overrides focusableElementsOffsetX.data-blobity-offset-y: Overrides focusableElementsOffsetY.data-blobity-magnetic: Overrides magnetic behavior.data-blobity-radius: Overrides radius.Additionally, you can exclude an element from being focusable by adding the data-no-blobity attribute.
<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 default value, I will not be considered focusable element.</div>You can include Blobity in your site by adding a <script> tag. This method creates a global Blobity object.
Use the downloaded version from the repository:
<script src="./dist/blobity.min.js"></script>Use the hosted version from the CDN. This version supports an autoStart feature which initializes Blobity with default options if the parameter is provided in the URL.
Warning: Do not load and auto-initialize Blobity in the <head> tag, as the <body> may not exist yet, leading to a document.body is null error.
<script src="https://cdn.blobity.gmrchk.com/by.js?autoStart&licenseKey=..."></script><script src="https://cdn.blobity.gmrchk.com/by.js?autoStart&licenseKey=..."></script>For modern development workflows, install Blobity as a node module. This version is unbundled, does not pollute the global scope, is smaller, and supports tree-shaking. It also includes additional utilities for frameworks like React.
npm install blobity --save
# or
yarn add blobitynpm install blobity --saveTo start Blobity, create a new instance of the Blobity class. You can pass an options object to the constructor.
Important: Blobity creates a <canvas> element inside the <body>. You must ensure the <body> is present on the page at the time of initialization. It is recommended to initialize Blobity as late as possible (e.g., just before the closing </body> tag) to avoid errors.
If using the script tag method:
const options = { color: 'rgb(180, 180, 180)' };
new Blobity(options);If using the npm/yarn package:
import Blobity from 'blobity';
const options = { color: 'rgb(180, 180, 180)' };
new Blobity(options);import Blobity from 'blobity';
const options = { color: 'rgb(180, 180, 180)' };
new Blobity(options);If you are using the Blobity script via CDN (https://cdn.blobity.gmrchk.com/by.js), you can trigger automatic initialization by adding the autoStart query parameter to the script's src URL. When autoStart is present, Blobity will automatically instantiate itself and attach to window.blobity. You must also provide a licenseKey via the licenseKey query parameter.
Example script tag:
<script src="https://cdn.blobity.gmrchk.com/by.js?autoStart&licenseKey=YOUR_KEY"></script>To use Blobity, instantiate the Blobity class. You can pass an optional Partial<Options> object to the constructor to customize the behavior and appearance of the blob. If no licenseKey is provided, a warning will be logged in the console.
import Blobity from './Blobity';
const blobity = new Blobity({
licenseKey: 'YOUR_LICENSE_KEY',
color: 'rgb(180, 180, 180)',
size: 40,
// ... other options
});The reset method disables the effects of the focusElement and showTooltip methods.
const blobity = new Blobity();
blobity.reset();Since Blobity instances should be created once, use the useBlobity hook for React applications. This hook accepts the same options as the standard Blobity constructor and returns a React ref of the instance. Import it from blobity/lib/react/useBlobity.
import useBlobity from 'blobity/lib/react/useBlobity';
const Component = () => {
const blobity = useBlobity({
licenseKey: '...'
});
return <div />;
};The focusElement method accepts a DOM element and forces a highlight on that specific element, regardless of the current mouse position. This is useful for drawing user attention to a specific part of the page.
const blobity = new Blobity();
const element = document.getElementById('some-important-button');
blobity.focusElement(element);The bounce method makes the current Blobity form (whether it is a blob, tooltip, or other shape) perform a single bounce animation.
const blobity = new Blobity();
blobity.bounce();