Cursor Trail: a custom cursor that reacts to your page

How to use it

1. Add one attribute to the body tag

<body data-cursor-trail>

2. Add the script before the closing body tag

<script src="cursor.js"></script>

That is all. Links, buttons and labels make the ring grow without any extra code.

Show a word on hover

Add data-cursor-text to any element. The ring turns into a filled circle with your word inside. Keep the word short, one word works best.

<a href="/project" data-cursor-text="View">
  <img src="project.jpg" alt="Project name">
</a>

<div class="slider" data-cursor-text="Drag"> ... </div>

To make the ring grow on something that is not a link, add data-cursor to it.

<div class="card" data-cursor> ... </div>

Options

Put the options on the same tag as data-cursor-trail.

<body data-cursor-trail
      data-cursor-color="#22d3ee"
      data-cursor-size="44"
      data-cursor-trail-length="12"
      data-cursor-lag="0.12">

Use it from JavaScript

Start it yourself when you want to change it later, for example with a theme switch.

var cursor = CursorTrail({ color: '#ff5c8a', size: 40, trail: 10 });

cursor.set('color', '#22d3ee');   // change any option later
cursor.moveTo(300, 200);          // move it yourself, for a product tour
cursor.destroy();                 // remove it and bring the normal cursor back

What it does on its own

• Phones and tablets. There is no mouse, so nothing is hidden. The trail shows only while a finger drags over the page and fades when it lifts. It never blocks a tap.
• Form fields. Over inputs, text areas and select boxes the effect fades out and the normal cursor returns. Typing and selecting text stay easy.
• Reduced motion. Visitors who switched off animations get the ring without the trail and without the delay.
• No wasted work. It only draws while the pointer moves. When the pointer rests, the script does nothing.
• Keyboard and screen readers. The cursor is decoration only and hidden from screen readers. Focus outlines are not touched.

Tips for a good custom cursor

• Keep the dot. The dot sits exactly under the pointer. Visitors aim with it, the ring is only decoration.
• Use the blend option on mixed pages. A purple ring disappears on a purple section. With data-cursor-blend it is always visible.
• Do not make the ring too slow. Below 0.1 it feels heavy after a minute. The default is a safe middle.
• Use labels sparingly. "View" on project pictures helps. A label on every link is noise.

Common questions

The normal arrow still shows on some elements.

Your own CSS probably sets cursor: pointer with !important there. Remove that rule, or accept the arrow on that element.

Does it work with WordPress, Shopify or Webflow?

Yes. Upload cursor.js, load it in the footer and add data-cursor-trail to the body tag. If you cannot edit the body tag, start it with one line: CursorTrail();

The cursor is hidden behind my popup.

The cursor layer uses a very high z-index. A popup inside an iframe or a browser dialog is a separate layer, and there the normal cursor shows instead.

Can I use a picture as the cursor?

The kit draws circles. For a picture, style .ct-dot with a background image in your own CSS and set the trail length to 0.

What is in the download

• cursor.js the script, about 9 KB with comments. The styles are included.
• index.html and demo.css the demo page you see above
• README.txt and LICENSE.txt the short guide and the MIT licence

Licence

MIT licence. Use it in personal and commercial projects, change it as you like. A link back is welcome and not required.