with-custom-cursor

A Higher-Order Component (HOC) library for React that enables you to easily add a custom cursor to any component.

Features

• Wrap any component with a custom cursor that follows mouse movement.
• Fully typed with TypeScript.
• Easy integration and customization.

Installation

npm install with-custom-cursor
# or
yarn add with-custom-cursor

Usage

1. Create Your Custom Cursor Component

import { type RefObject } from "react"

type CursorProps = {
    ref: RefObject<HTMLDivElement> // required to work!
}
export const Cursor = ({ ref }: CursorProps) => {
    return (
        <div className="cursor" ref={ref}>
            <label>see more</label>
        </div>
    )
}

2. Styling

.cursor {
    width: 16rem;
    height: 16rem;
    background-color: #fff;
    align-items: center;
    justify-content: center;
    border-radius: 50%;
    position: absolute;
    z-index: 9;
    display: flex;
}

.cursor label {
  color: #252525;    
  font-size: 1.8rem;
  font-weight: 400;
}

3. Wrap Your Component

import { WithCustomCursor } from "with-custom-cursor"
import { Cursor } from "./cursor"

const Card = () => {
    return (
        <div className="card">
            <h1>Card</h1>
            <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, voluptatibus.</p>
        </div>
    )
}

export const CardWithCursor = WithCustomCursor(Card, Cursor)

API

WithCustomCursor(WrappedComponent, CursorComponent)

• WrappedComponent: The component you want to enhance with a custom cursor.
• CursorComponent: The cursor component (must accept a ref prop).

Returns a new component that renders your cursor and the wrapped component.

Example

Adding Animations

Animating your custom cursor is straightforward with with-custom-cursor , as it is fully compatible with any React-friendly animation or CSS library.

1. Style Your Cursor Component

First, remove position: absolute and pointer-events: none from your cursor's style. These will be handled by the wrapper, allowing your cursor to animate freely:

.cursor {
    width: 16rem;
    height: 16rem;
    background-color: #fff;
    align-items: center;
    justify-content: center;
    border-radius: 50%;
    z-index: 9;
    display: flex;
}

2. Add Animation to Your Cursor

Wrap your cursor component in a <div> (recommended) or any html element with position: absolute and pointer-events: none (these styles were removed from the cursor itself). You can now use any animation library, such as framer-motion , tailwindcss , or gsap , etc... To animate your cursor.

Below is an example using framer-motion to create a pulsing effect:

import { motion } from "framer-motion"
import { type RefObject } from "react"

type CursorProps = {
    ref: RefObject<HTMLDivElement>
    label: string
    color?: string
}

export const Cursor = ({ label, color="white", ref}: CursorProps) => {
    return (
        <div ref={ref} style={{ position: "absolute", pointerEvents: "none" }}>
            <motion.div
            className="cursor"
            style={{ backgroundColor: color }}
            animate={{
                scale: [1, 1.2, 1]
            }}
            transition={{
                duration: 1.5,
                repeat: Infinity,
                ease: "easeInOut",
            }}
            >
                <label>{label}</label>
            </motion.div>
        </div>
        
    )
}

That's it! You can now add any animation to your custom cursor component. Feel free to experiment with different libraries and effects to achieve the look and feel you want.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

A special thanks to my friend Gabriel Chelles!

License

MIT © Andre Quintero dos Santos