with-custom-cursor
Version:
A Higher-Order Component (HOC) library for React that enables you to easily add a custom cursor to any component.
160 lines (122 loc) • 4.06 kB
Markdown
# 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
```bash
npm install with-custom-cursor
# or
yarn add with-custom-cursor
```
## Usage
### 1. Create Your Custom Cursor Component
```tsx
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
```css
.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
```tsx
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
<img src="cursor-min.gif" alt="Custom Cursor Example" style="width:50%;max-width:320px;min-width:160px;" />
## 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:
```css
.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:
```tsx
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