Custom cursor animation on website

Implementation of Custom Cursor Animation on Website

Custom cursor is one of those elements where the difference between "done" and "done well" is immediately visible. Bad implementation gives a feeling of heaviness: cursor lags, jerks, conflicts with native browser states. Correct one works invisibly, enhances interface character.

Anatomy of Custom Cursor

Typical structure: two elements — dot, which follows the mouse without delay, and ring/follower, which lags with lerp effect. Instead of cursor: none on entire document — hide only where needed.

* {
  cursor: none;
}

.cursor-dot {
  position: fixed;
  width: 8px;
  height: 8px;
  border-radius: 50%;
  background: #fff;
  pointer-events: none;
  z-index: 9999;
  transform: translate(-50%, -50%);
  will-change: transform;
}

.cursor-ring {
  position: fixed;
  width: 36px;
  height: 36px;
  border-radius: 50%;
  border: 1.5px solid rgba(255, 255, 255, 0.6);
  pointer-events: none;
  z-index: 9998;
  transform: translate(-50%, -50%);
  will-change: transform;
}

Movement Logic

Animation via requestAnimationFrame with linear interpolation for follower. Dot position updates directly via mousemove — without lerp, otherwise precision feeling is lost.

interface CursorState {
  mouse: { x: number; y: number }
  follower: { x: number; y: number }
  isHovering: boolean
  isVisible: boolean
}

class CustomCursor {
  private dot: HTMLElement
  private ring: HTMLElement
  private state: CursorState
  private rafId: number | null = null
  private readonly LERP = 0.12

  constructor() {
    this.dot = document.querySelector('.cursor-dot')!
    this.ring = document.querySelector('.cursor-ring')!
    this.state = {
      mouse: { x: -100, y: -100 },
      follower: { x: -100, y: -100 },
      isHovering: false,
      isVisible: false,
    }

    this.init()
  }

  private init() {
    document.addEventListener('mousemove', this.onMouseMove)
    document.addEventListener('mouseenter', this.onMouseEnter)
    document.addEventListener('mouseleave', this.onMouseLeave)

    // Hover states for interactive elements
    document.querySelectorAll('a, button, [data-cursor]').forEach((el) => {
      el.addEventListener('mouseenter', this.onElementEnter)
      el.addEventListener('mouseleave', this.onElementLeave)
    })

    this.tick()
  }

  private onMouseMove = (e: MouseEvent) => {
    this.state.mouse.x = e.clientX
    this.state.mouse.y = e.clientY

    // Dot follows without delay via CSS transform
    this.dot.style.left = `${e.clientX}px`
    this.dot.style.top = `${e.clientY}px`
  }

  private tick = () => {
    // Follower with lerp
    this.state.follower.x += (this.state.mouse.x - this.state.follower.x) * this.LERP
    this.state.follower.y += (this.state.mouse.y - this.state.follower.y) * this.LERP

    this.ring.style.left = `${this.state.follower.x}px`
    this.ring.style.top = `${this.state.follower.y}px`

    this.rafId = requestAnimationFrame(this.tick)
  }

  private onElementEnter = (e: Event) => {
    const target = e.currentTarget as HTMLElement
    const cursorType = target.dataset.cursor || 'hover'
    this.setState('hover', cursorType)
  }

  private onElementLeave = () => {
    this.setState('default')
  }

  private setState(state: string, type?: string) {
    this.ring.className = `cursor-ring cursor-ring--${state}`
    if (type) this.ring.dataset.cursorType = type
  }

  destroy() {
    if (this.rafId) cancelAnimationFrame(this.rafId)
    document.removeEventListener('mousemove', this.onMouseMove)
  }
}

Cursor States

Standard set: default, hover (on links), active (on click), text (on paragraphs), drag (on sliders), view (on media). Switching via CSS classes and data attributes.

/* Hover on buttons — enlarge with fill */
.cursor-ring--hover {
  width: 52px;
  height: 52px;
  background: rgba(255, 255, 255, 0.1);
  border-color: transparent;
  transition: width 0.25s ease, height 0.25s ease, background 0.25s ease;
}

/* Text mode — vertical bar */
.cursor-ring--text {
  width: 2px;
  height: 28px;
  border-radius: 1px;
  background: #fff;
  border: none;
}

/* View/play — cursor with text */
.cursor-ring[data-cursor-type="view"]::after {
  content: 'VIEW';
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  font-size: 9px;
  font-weight: 700;
  letter-spacing: 0.1em;
  color: #fff;
}

Integration with React

In React projects, cursor is implemented as global component via Context or store. Important: mount only once, don't rerender on every mouse movement.

import { useEffect, useRef, useCallback } from 'react'
import { useMotionValue, useSpring, motion } from 'framer-motion'

export function CustomCursor() {
  const mouseX = useMotionValue(-100)
  const mouseY = useMotionValue(-100)

  // Spring for follower — alternative to manual RAF+lerp
  const springConfig = { damping: 25, stiffness: 200, mass: 0.5 }
  const followerX = useSpring(mouseX, springConfig)
  const followerY = useSpring(mouseY, springConfig)

  useEffect(() => {
    const onMove = (e: MouseEvent) => {
      mouseX.set(e.clientX)
      mouseY.set(e.clientY)
    }

    window.addEventListener('mousemove', onMove)
    return () => window.removeEventListener('mousemove', onMove)
  }, [])

  // Hide on touch devices
  const isTouchDevice = window.matchMedia('(hover: none)').matches
  if (isTouchDevice) return null

  return (
    <>
      <motion.div
        className="cursor-dot"
        style={{ x: mouseX, y: mouseY, translateX: '-50%', translateY: '-50%' }}
      />
      <motion.div
        className="cursor-ring"
        style={{ x: followerX, y: followerY, translateX: '-50%', translateY: '-50%' }}
      />
    </>
  )
}

Native Cursor as Fallback

On touch devices custom cursor is disabled entirely. cursor: none is applied only with (hover: hover) and (pointer: fine):

@media (hover: hover) and (pointer: fine) {
  * { cursor: none; }
  .cursor-dot, .cursor-ring { display: block; }
}

@media (hover: none), (pointer: coarse) {
  .cursor-dot, .cursor-ring { display: none; }
}

Common Pitfalls

Flickering on fast movement — dot and ring render in different layers. Solution: both elements in one stacking context, will-change: transform on each.

Conflict with iframe — when cursor enters iframe, mousemove event doesn't fire. Need to track mouseleave on document and hide cursor.

CSS transitions delay — if ring has transition without excluding left/top, follower loses liveliness. Transitions only for scale/opacity/color, position via transform without transition.

Timeframes

Basic implementation with dot + ring and hover states — 1 day. With text animation, drag cursor for sliders, integration in existing React project and full state set — 2–3 days.