tooyoung:blobity-cursor

Blobity Cursor

Add a canvas-based custom cursor effect to landing pages. The cursor follows the mouse with spring physics, expands to wrap interactive elements, and inverts colors via mix-blend-mode: difference.

Core mechanism: Blobity creates a <canvas> overlay (position: fixed, pointer-events: none, z-index: max) and draws a blob that follows the cursor using the Kinet spring physics engine. With invert: true, the canvas uses mix-blend-mode: difference to create a color-inversion effect.

Quick Start (HTML)

Minimal working example — copy into any HTML page:

<!-- Hide default cursor -->
<style>
  body.blobity-active,
  body.blobity-active a,
  body.blobity-active button,
  body.blobity-active [data-blobity],
  body.blobity-active [data-blobity-tooltip] {
    cursor: none !important;
  }
</style>

<!-- Load Blobity via ESM CDN (npm: import Blobity from 'blobity') -->
<script type="module">
  import Blobity from "https://esm.sh/blobity@0.2.3";

  // Skip touch devices
  if ("ontouchstart" in window || navigator.maxTouchPoints > 0) {
    throw new Error("Touch device — skip Blobity");
  }

  const blobity = new Blobity({
    licenseKey: "opensource",
    invert: true,
    zIndex: 50,
    color: "#ffffff", // Canvas fill → difference with dark bg = light
    dotColor: "#10b981", // Resting cursor dot color
    radius: 6,
    magnetic: false,
    mode: "normal",
    focusableElements: "a, button, [data-blobity], [data-blobity-tooltip]",
    focusableElementsOffsetX: 5,
    focusableElementsOffsetY: 4,
    font: "'JetBrains Mono', monospace",
    fontSize: 16,
    fontWeight: 600,
    fontColor: "#0d1117", // Tooltip text color on canvas
    tooltipPadding: 12,
  });

  document.body.classList.add("blobity-active");
</script>

Add data-blobity-tooltip="Label text" to any element for tooltip mode:

<div class="card" data-blobity-tooltip="View details">...</div>

Installation

CDN (no build tool):

<script type="module">
  import Blobity from "https://esm.sh/blobity@0.2.3";
</script>

Other CDNs (cdn.jsdelivr.net, cdn.blobity.dev) have known 404/connection issues. Use esm.sh.

npm (with bundler):

# pnpm (recommended)
pnpm add blobity

# npm
npm install blobity

# yarn
yarn add blobity

import Blobity from "blobity";

Blobity has react and vue as optional peer dependencies. Ignore the warning if you're not using their bindings.

Theme Adaptation (Light/Dark)

The mix-blend-mode: difference formula is |page_pixel - canvas_pixel|. This means:

• Dark page + white canvas → light result (standard inversion) ✓
• Light page + dark canvas → light result (soft tint) ✓
• Light page + white canvas → black result (harsh) ✗

Key rule: dark bg uses white color, light bg uses a dark color calculated from your target tint.

Recommended Color Scheme

Option	Dark Mode	Light Mode	Notes
color	#ffffff	#190a11	Light mode produces soft mint #e6f5ee on white
dotColor	#10b981	#111827	Accent green / dark gray
fontColor	#0d1117	#000000	Tooltip text: dark→black on light bg, light→white on dark bg after difference

Theme Switching Pattern

Watch for theme attribute changes and update Blobity options dynamically:

const isDark = () =>
  document.documentElement.getAttribute("data-theme") !== "light";
// Alternative checks:
//   document.documentElement.classList.contains('dark')
//   window.matchMedia('(prefers-color-scheme: dark)').matches

const observer = new MutationObserver(() => {
  blobity.updateOptions({
    color: isDark() ? "#ffffff" : "#190a11",
    dotColor: isDark() ? "#10b981" : "#111827",
    fontColor: isDark() ? "#0d1117" : "#000000",
  });
});

observer.observe(document.documentElement, {
  attributes: true,
  attributeFilter: ["data-theme", "class"],
});

To calculate custom light-mode colors, see references/color-math.md.

Configuration Options

Option	Type	Default	Description
licenseKey	string	—	Use 'opensource' for open-source projects
invert	boolean	false	Enable mix-blend-mode: difference on canvas
color	string	'#000000'	Canvas fill color when hovering focusable elements
dotColor	string	'#000000'	Resting cursor dot color
radius	number	4	Dot radius in pixels
magnetic	boolean	true	Whether cursor snaps to element center on hover
mode	string	'normal'	Cursor mode
zIndex	number	-1	Canvas z-index
focusableElements	string	'a, button'	CSS selector for interactive elements
focusableElementsOffsetX	number	0	Horizontal padding when wrapping elements
focusableElementsOffsetY	number	0	Vertical padding when wrapping elements
font	string	—	Tooltip font family
fontSize	number	16	Tooltip font size
fontWeight	number	400	Tooltip font weight
fontColor	string	'#000000'	Tooltip text color on canvas
tooltipPadding	number	4	Tooltip inner padding

Tooltip Mode

Add data-blobity-tooltip to elements — cursor morphs into a text label instead of expanding:

<div class="step-card" data-blobity-tooltip="Step 1: Upload">...</div>
<a href="/docs" data-blobity-tooltip="Documentation">Docs</a>

Tooltip elements should be included in focusableElements via [data-blobity-tooltip] selector.

Light mode tooltip text visibility: tooltip background gets darkened by difference blend, so fontColor must also produce a light result after blending. Use #000000 for light mode (becomes white after |#fff - #000| = #fff).

Common Pitfalls

1. CDN 404 Errors

✗ cdn.jsdelivr.net/npm/blobity@latest/lib/blobity.min.js  → wrong path
✗ cdn.blobity.dev/by.js                                    → server down
✗ cdn.jsdelivr.net/npm/blobity@0.2.4                       → version doesn't exist
✓ esm.sh/blobity@0.2.3                                     → works

2. Cursor Invisible or Pure Black on Light Background

This is a mix-blend-mode: difference color math issue. See the Theme Adaptation section — use a dark color value for light backgrounds (NOT white).

3. Touch Device Detection

Always skip Blobity on touch devices — there's no mouse cursor to replace:

const isTouchDevice = "ontouchstart" in window || navigator.maxTouchPoints > 0;
if (isTouchDevice) return;

4. SPA Page Navigation Cleanup

Blobity must be destroyed on route change to avoid canvas leaks:

// Astro view transitions
document.addEventListener(
  "astro:before-swap",
  () => {
    observer.disconnect();
    document.body.classList.remove("blobity-active");
    blobity.destroy();
  },
  { once: true },
);

// React Router / Vue Router
onUnmounted(() => {
  blobity.destroy();
});
// Or useEffect cleanup in React

5. Peer Dependency Warnings

Blobity declares react and vue as peer deps. Safe to ignore if not using their framework bindings:

# pnpm
pnpm add blobity --no-strict-peer-dependencies

# npm (if needed)
npm install blobity --legacy-peer-deps

6. z-index Conflicts

Set zIndex high enough to overlay page content but below modals/dialogs. 50 works for most cases. If your site has a sticky header at z-index: 100+, either raise Blobity's value or accept the cursor rendering behind the header.

Scroll Bounce

Add a playful bounce effect when user scrolls:

let scrollTimeout = null;
window.addEventListener(
  "scroll",
  () => {
    if (scrollTimeout) return;
    scrollTimeout = setTimeout(() => {
      blobity.bounce();
      scrollTimeout = null;
    }, 150);
  },
  { passive: true },
);

References

File	Content
references/frameworks.md	React hook, Vue 3 composable, Vue 2 mixin — complete templates
references/color-math.md	mix-blend-mode: difference color calculation, lookup table, reverse formula