bee-react-animated-cursor

React Animated Cursor (Optimize by Mahalyka)

A React functional component that replaces the native cursor with a custom animated jawn. As this is a function component, hooks manage events, local state and RAF.

Contents

1. 📌 Features
2. 🎯 Quickstart
3. 🤖 Commands
4. 🧬 Options
5. 🕹️ Usage
6. 🎨 Cursor Types
7. 📓 Notes
8. 📅 To Dos

📌 Features

The custom cursor is comprised of

• An inner dot (cursorInner)
• An outer, outlining circle (cursorOuter), with slight opacity based on the dot/primary color
• A slight trailing animation of the outer outline
• An inversely scaling effect between the inner and outer cursor parts on click or link hover

Options exist for modifying the color and scaling of the cursor elements (see props/options below). Style props for in the inner and outer cursor allow you to easily create unique cursor types.

Live Demo

🎯 Quickstart

Install package from npm

npm i react-animated-cursor

Add to you project

Add to a global location, like _app.js

import React from "react";
import AnimatedCursor from "react-animated-cursor"

export default function App() {
  return (
    <div className="App">
      <AnimatedCursor />
    </div>
  );
}

Add to Next.js

If using in Next, you may have to leverage dynamic imports.

import dynamic from 'next/dynamic'

const AnimatedCursor = dynamic(() => import('react-animated-cursor'), {
  ssr: false
});

<AnimatedCursor/>

🤖 Commands

Install npm i react-animated-cursor
Build: npm run build
Dev: npm run dev
Demo Run: npm run demo:start
Demo Build: npm run demo:build
Demo Clean: npm run demo:clean

Demo

The demo is bundled with Parcel.js and served up at http://localhost:1234/.

Dist

On build, lib populates dist with commonjs, es, umd versions of the component.

🕹️ Usage

import React from "react";
import AnimatedCursor from "react-animated-cursor"


export default function App() {
  return (
    <div className="App">
      <AnimatedCursor />
    </div>
  );
}

Example Usage - with options

import React from "react";
import AnimatedCursor from "react-animated-cursor"

export default function App() {
  return (
    <div className="App">
    <AnimatedCursor
      innerSize={8}
      outerSize={8}
      color='193, 11, 111'
      outerAlpha={0.2}
      innerScale={0.7}
      outerScale={5}
      clickables={[
        'a',
        'input[type="text"]',
        'input[type="email"]',
        'input[type="number"]',
        'input[type="submit"]',
        'input[type="image"]',
        'label[for]',
        'select',
        'textarea',
        'button',
        '.link'
      ]}
    />
    </div>
  );
}

With Next / SSR (Server Side Rendering)

In Next's SSR environment, you may have to leverage a Dynamic Import.

import dynamic from 'next/dynamic'

const AnimatedCursor = dynamic(() => import('react-animated-cursor'), {
  ssr: false
});

<AnimatedCursor/>

🧬 Options

Option	Type	Description	Default
color	string	rgb value	220, 90, 90
outerAlpha	number	amount of alpha transparency for outer cursor dot	0.4
innerSize	number	Size (px) of inner cursor dot	8
outerSize	number	Size (px) of outer cursor outline	8
innerScale	number	amount dot scales on click or link hover	0.7
outerScale	number	amount outer dot scales on click or link hover	5
innerStyle	object	provides custom styles / css to inner cursor	null
outerStyle	object	provides custom styles / css to outer cursor	null
trailingSpeed	number	Outer dot's trailing speed	8
clickables	array	Collection of selectors cursor that trigger cursor interaction	['a', 'input[type="text"]', 'input[type="email"]', 'input[type="number"]', 'input[type="submit"]', 'input[type="image"]', 'label[for]', 'select', 'textarea', 'button', '.link']

🎨 Cursor Types

You can use the innerStyle and outerStyle props to provide custom styles and create a variery of custom cursor types. For example:

Donut Cursor

A donut style cursor basically resembles a donut. You can easily create on by applying using the outerStyle props to apply an outer border

<AnimatedCursor
  color="255,255,255"
  innerSize={8}
  outerSize={35}
  innerScale={1}
  outerScale={1.7}
  outerAlpha={0}
  outerStyle={{
    border: '3px solid #fff'
  }}
/>

Dynamic Styles

Use CSS Vars with innerStyle and outerStyle props to create dynamic styles values that you can easily update. For example, perhaps you have a light and dark mode experience and what your cursor to also adapt it's colors.

CSS Vars

html {
  --cursor-color: #333
}

html.dark-mode {
  --cursor-color: #fff
}

Pass CSS Var as Style Props

<AnimatedCursor
  innerSize={8}
  outerSize={35}
  innerScale={1}
  outerScale={1.7}
  outerAlpha={0}
  hasBlendMode={true}
  outerStyle={{
    border: '3px solid var(--cursor-color)'
  }}
  innerStyle={{
    backgroundColor: 'var(--cursor-color)'
  }}
/>

BlendMode Cursor

You can use CSS mix-blend-mode with the style props to create an intersting cursor effect on hover tha inverts the content's color. Works best with white / black cursors.

<AnimatedCursor
  color="#fff"
  innerSize={8}
  outerSize={35}
  innerScale={1}
  outerScale={1.7}
  outerAlpha={0}
  hasBlendMode={true}
  outerStyle={{
    mixBlendMode: 'exclusion'
  }}
/>

📓 Notes

Mobile / Touch

helpers/isDevice.js uses UA sniffing to determine if on a common device so we can avoid rendering cursors

📅 To Dos

• Either remove on mobile, or provide touch events.
• Separate click and hover scalings to provide a different scaling when clicking on links
• Fix transform blur in Safari
• Make clickables (cursor targets / selectors) a prop
• Add PropType checks
• Add PropType checks
• Open cursor styles as props
• Solution for impacting state during route changes
• Convert to TS

Have fun ya'll.