Getting Started

Aura adds themed drop shadows to your cursor. The shadow color updates automatically when your theme changes.

Still in beta. Works best in Chrome and Chromium-based browsers. Safari support is improving.

Installation

npm install cursor-aura

React

Add the component anywhere in your app. Use a CSS variable for the color to avoid hydration flashes when server-rendering with a persisted theme:

import { Aura } from 'cursor-aura'

export default function App() {
  return (
    <>
      <Aura color="var(--your-theme-color)" />
      {/* rest of your app */}
    </>
  )
}

Or pass a static color directly:

<Aura color="#0C3EFF" />

Vanilla JS

For non-React sites:

<script type="module">
  import { AuraVanilla as Aura } from 'https://esm.sh/cursor-aura/vanilla'

  Aura.init({ color: '#0C3EFF' })

  // Update color later
  // Aura.setColor('#FF6183')

  // Clean up
  // Aura.destroy()
</script>

For iframes or pop-out windows, pass the target document:

Aura.init({
  color: '#0C3EFF',
  document: iframe.contentDocument
})

Theming & SSR

If your app persists a theme preference (e.g. to localStorage), the cursor shadow can flash the wrong color on page load. The server renders with the default theme, then React hydrates and applies the saved theme — but there's a visible frame in between.

Fix this with an inline script that sets the correct theme before React hydrates:

// In your root layout (e.g. layout.tsx)
<html data-theme="default">
  <head>
    <script dangerouslySetInnerHTML={{ __html: `
      try {
        var t = localStorage.getItem('my-theme');
        if (t) document.documentElement.setAttribute('data-theme', t);
      } catch(e) {}
    `}} />
  </head>
  <body>{children}</body>
</html>

Then use a CSS variable for the Aura color so it resolves from the pre-set attribute:

/* CSS */
[data-theme="blue"]   { --theme-color: #0C3EFF; }
[data-theme="pink"]   { --theme-color: #FF6183; }

/* React */
<Aura color="var(--theme-color)" />

The Aura component automatically watches for data-theme, class, and style attribute changes on the document root and re-resolves CSS variables when they change.

API Reference

React: `<Aura />`

Prop	Type	Default	Description
`color`	string	'#000'	Shadow color. Accepts hex, rgb, hsl, or a CSS variable like `var(--color)`.

Vanilla JS: `Aura`

Method	Description
`Aura.init(options?)`	Initialize. Options: `color` (string, default `'#000'`), `document` (Document, for iframes/portals).
`Aura.setColor(color)`	Update the shadow color at any time.
`Aura.destroy()`	Remove all cursor styles, event listeners, and caches.

Accessibility

Aura is designed to be unobtrusive:

Touch-only devices: Automatically skipped when no mouse or trackpad is detected
Portal-safe: Works correctly inside iframes, portals, and pop-out windows
Clean unmount: All styles and event listeners are removed when the component unmounts