Dev

Animated Cursor

A pure JS animated cursor library

I recently released a new JS lib on npm called Animated Cursor.

It’s a pure / vanilla JS module for replacing the browser’s native cursor with a custom animated cursor. It’s similar to another package of mine called React Animated Cursor… only this version is not for React. It’s just JavaScript.

📌 Features

  • Small (4kb compiled file) and dependency free, pure JavaScript library.
  • Replaces native Cursor with a custom (and performant) animated cursor.
  • Cursor is just a DOM element, comprised of inner dot and outer circle with trailing animation. Cursor elements inversely scale on click and hover.
  • Customizable, with options to customize color, sizes, scaling percentages, and more.
  • Bails on touch devices.
  • Hybrid NPM Module supporting import and require

More the specifically, the cursor is made of

  • An inner dot.
  • An outer, outlining circle, with slight opacity based on the inner cursor’s color.
  • A slight trailing animation of the outer cursor.
  • An inversely scaling effect between the inner and outer cursor parts on click or hover of defined clickable elements.
  • Outer cursor can also be just a border to create a Donut style cursor.
  • Outer cursor can have a blend-mode applied for an exclusion effect over hovered text / elements.

Cursor Demo | Repo

🎯 Quickstart

Install (via npm)

npm i animated-cursor

Add markup for cursor

<div id="cursor">
  <div id="cursor-outer"></div>
  <div id="cursor-inner"></div>
</div>

Init cursor

Import and initialize. This example uses defaults but AnimatedCursor accepts a single options parameter (see full options).


import AnimatedCursor from 'animated-cursor'

// Using just default options 
const cursor = AnimatedCursor()

cursor.init()

Or by require

Being a hybrid module, you can also require.


const AnimatedCursor = require('animated-cursor')
const cursor = AnimatedCursor()
cursor.init()

Check the default cursor demo

🧬 Provide Options

AnimatedCursor accepts options to customize stuff like cursor color, size, scaling animation, etc. See the docs / readme for the full list of available options.

Example init with some options


import AnimatedCursor from 'animated-cursor'

// cursor options
let options = {
  color: '#0ff',
  outerAlpha: 0.25,
  size: { 
    inner: 8, 
    outer: 38 
  },
  hoverScale: {
    inner: 0.5,
    outer: 1.4
  },
  clickScale: {
    inner: 1.4,
    outer: 0.1
  }
}

// Create Cursor instance
const cursor = AnimatedCursor(options)

// Init Cursor
cursor.init()

Create a Donut cursor

The outerBorderSize option applies a border to the outer cursor. You can leverage this to create a Donut style cursor:

  1. Set outerAlpha option to 0 (or almost 0).
  2. Provide a numeric value for outerBorderSize option.

import AnimatedCursor from 'animated-cursor'

// Options to create a Donut cursor
let donutOpts = {
  color: '#0ff',
  outerAlpha: 0,
  outerBorderSize: 3
}

const cursor = AnimatedCursor(donutOpts)

cursor.init()

Check the Donut cursor demo

Create a Blend-mode cursor

You can create a neat Blend-mode cursor that filters the hovered text through the cursor. This probably works best with White / Black cursors.

  1. Set hasOuterBlendMode: true
  2. Set outerAlpha to 1 or close to 1.
  3. Probs use a cursor color like #fff or #000.

import AnimatedCursor from 'animated-cursor'

// Options to create a blend-mode cursor.
// Cursor is white, page background-color is dark.
 let blendOpts = {
    hasOuterBlendMode: true,
    color: '#fff',
    outerAlpha: 1
 }

const cursor = AnimatedCursor(blendOpts)

cursor.init()

Check the Blend-mode cursor demo

Github

You can go check AnimatedCursor on the Githubs, Right Here. Take a look, let me know if you have any issues or feature ideas.

📅 ToDos

  • Maybe make different cursor types available as presets?
  • Add a proper destory method to kill off the custom cursor
Read Next

Read Smore, v2

Read Story