API References

Complete reference for every HTML attribute, CSS custom property, and JavaScript function exposed by animated-cursor.js and animated-cursor.css.

v1.1.0 — June 2026
All examples below assume you have loaded animated-cursor.css and animated-cursor.js in your page. See the Docs for setup instructions.

HTML Data Attributes

Set these attributes directly on the <body> element to configure the cursor appearance and theme.

Attribute Type Default Accepted Values Description
data-cursor string "orb" orb · ring · diamond · crosshair Selects the visual shape of the animated cursor.
data-theme string "galaxy" galaxy · aurora · neon · firefly Sets the overall colour palette for the cursor, particles, and background.

Example

HTML 
<!-- Neon Ring cursor + Neon colour theme -->
<body data-cursor="ring" data-theme="neon">

  <!-- Change at runtime via JavaScript -->
  <script>
    document.body.dataset.cursor = "diamond";
    document.body.dataset.theme  = "aurora";
  </script>
</body>

CSS Classes

Apply these classes to elements or the body to control cursor behaviour and theming.

Class Applied To Effect
magnetic-control Any interactive element Triggers the cursor's hover-expand state (is-hovering) when the pointer enters the element.
light-theme <body> Switches the entire page (navbar, footer, cursor, background) to the light colour mode.
cursor <div> (required) Marks the element that the JS will move and animate as the custom cursor.
is-hovering .cursor (auto-added) Applied automatically by the JS on hover/click. Enlarges the cursor and changes border colour.
background <div> (required) The full-screen radial gradient backdrop that reacts to cursor position.
galaxy-glow <div> (required) The large blurred glow blob that follows the cursor at low opacity.
glass-overlay <div> (required) Fixed overlay with backdrop-filter: blur for the glassmorphism effect.
Add magnetic-control to buttons, links, and cards to make the cursor respond visually when users hover over them — it dramatically improves UX.

CSS Custom Properties

Override any of these on :root or body in your own stylesheet to customise the design.

Property Type Default (Galaxy) Description
--accent color #ffd84a Primary glow colour — cursor, buttons, selected options.
--accent-rgb R, G, B 255, 216, 74 RGB channel values of --accent, used in rgba() helpers.
--accent-two color #57d8ff Secondary highlight colour — borders, links, select focus.
--accent-two-rgb R, G, B 87, 216, 255 RGB channel values of --accent-two.
--accent-three color #ff7ad9 Tertiary accent — sparkle particles, diamond cursor gradient.
--accent-three-rgb R, G, B 255, 122, 217 RGB channel values of --accent-three.
--page-bg color #05070d Base page background colour.
--text-color color #f8fbff Default text colour for body copy.
--glow-rgb R, G, B 138, 43, 226 Colour of the large .galaxy-glow blob behind the cursor.
--bg-one color #321252 First gradient stop of the background radial gradient (top-left).
--bg-two color #06364b Second gradient stop of the background radial gradient (bottom-right).
--bg-mid color #10131f Midpoint colour for the linear gradient behind the radial layers.
--cursor-x percentage 50% Read-only (set by JS). Current X position of the cursor as a viewport percentage. Used in the background radial gradient.
--cursor-y percentage 50% Read-only (set by JS). Current Y position of the cursor as a viewport percentage.

Example — Custom Palette

CSS 
/* your-styles.css — must load AFTER animated-cursor.css */
:root {
  --accent:           #00e5ff;  /* electric cyan */
  --accent-rgb:       0, 229, 255;
  --accent-two:       #ff6f00;  /* deep orange  */
  --accent-two-rgb:   255, 111, 0;
  --accent-three:     #76ff03;  /* lime green   */
  --accent-three-rgb: 118, 255, 3;
  --page-bg:          #030a0f;
  --bg-one:           #001a2c;
  --bg-two:           #1a0010;
  --glow-rgb:         0, 229, 255;
}

Theme Variables

Each built-in theme is implemented as a body[data-theme="…"] selector block that overrides the root tokens. You can create your own themes the same way.

Theme--accent--accent-two--accent-three--page-bg--glow-rgb
galaxy default #ffd84a #57d8ff #ff7ad9 #05070d 138, 43, 226
aurora #7dffca #8ea7ff #ff8ee6 #03130f 46, 255, 175
neon #ff2bd6 #00f5ff #b6ff00 #08030d 255, 43, 214
firefly #dfff74 #4dff8a #ffbd59 #050805 138, 255, 70

Adding a Custom Theme

CSS 
/* Define your own theme */
body[data-theme="lava"] {
  --page-bg:          #0d0300;
  --accent:           #ff4500;
  --accent-rgb:       255, 69, 0;
  --accent-two:       #ff9100;
  --accent-two-rgb:   255, 145, 0;
  --accent-three:     #ffeb3b;
  --accent-three-rgb: 255, 235, 59;
  --glow-rgb:         255, 69, 0;
  --bg-one:           #3d0000;
  --bg-two:           #1a0800;
  --bg-mid:           #0d0500;
}

/* Apply it */
document.body.dataset.theme = "lava";

JavaScript Functions

These internal functions are exposed on the window object and can be called from your own scripts.

function createClickBurst(x: number, y: number)

Triggers a sparkle burst of 42 particles radiating outward from the coordinates (x, y) in viewport pixels. Called automatically on every pointerdown event.

ParamTypeDescription
xnumberViewport X coordinate (pixels from left).
ynumberViewport Y coordinate (pixels from top).
function resizeCanvas()

Re-initialises the star canvas to match the current viewport dimensions and regenerates all star positions. Called automatically on window.resize and on theme change. You can call it manually after dynamically changing the viewport.

function getTheme() → object

Returns the current theme's particle colour arrays. Useful if you are building a custom particle effect that should stay in sync with the active colour palette.

JS — return shape 
// Returns an object like:
{
  sparkle: ["255, 216, 74", "87, 216, 255", "255, 122, 217"],
  stars:   ["255, 255, 255", "255, 216, 74",  "87, 216, 255"]
}

Events & Hooks

The library listens to the following native DOM events. You can attach your own listeners to the same events to extend behaviour.

EventTargetLibrary Action
pointermove document Updates targetX / targetY, shows cursor, triggers sparkle trail.
pointerleave document Hides cursor and glow, stops sparkle emission.
pointerdown document Calls createClickBurst() and briefly adds is-hovering to cursor.
pointerenter .magnetic-control Adds is-hovering to cursor element.
pointerleave .magnetic-control Removes is-hovering from cursor element.
change #cursor-design Updates body.dataset.cursor to the new value.
change #theme-design Updates body.dataset.theme and calls resizeCanvas() to recolour stars.
resize window Calls resizeCanvas() to adapt to the new viewport size.
click .theme button Toggles light-theme class on <body> and persists to localStorage.

Code Examples

Switch cursor design at runtime

JavaScript 
// Switch to Diamond cursor + Aurora theme
document.body.dataset.cursor = "diamond";
document.body.dataset.theme  = "aurora";

// Sync the hidden selects so the picker UI stays in sync
const cd = document.getElementById("cursor-design");
const td = document.getElementById("theme-design");
if (cd) cd.value = "diamond";
if (td) { td.value = "aurora"; resizeCanvas(); }

Trigger a click burst programmatically

JavaScript 
// Fire a sparkle burst at the centre of any element
function burstAt(el) {
  const r = el.getBoundingClientRect();
  createClickBurst(
    r.left + r.width  / 2,
    r.top  + r.height / 2
  );
}

document.querySelector(".my-button")
        .addEventListener("click", e => burstAt(e.currentTarget));

Toggle light mode from your own button

JavaScript 
const myBtn = document.getElementById("myThemeBtn");
myBtn.addEventListener("click", () => {
  const isLight = document.body.classList.toggle("light-theme");
  localStorage.setItem("lightMode", JSON.stringify(isLight));
});
The light/dark preference is stored under the key "lightMode" in localStorage. Toggling via your own code should also update this key so the preference persists on page reload.
Copied!