use-custom-cursor

Introduction
Installation
Basic usage
Components
Hooks

Introduction

This library is all about customizing the cursor with easy. This is still a really early concept in alpha. Nothing is yet definitive and you should NOT use this in production for now. This library has no other dependencies than react itself and polished.

Installation

Requirements

React 18^

This library is written with Typescript in mind, but you can use it with Javascript.

Node/npm

To install use-custom-cursor:

npm install use-custom-cursor@alpha   # npm
yarn add use-custom-cursor@alpha      # yarn
pnpm add use-custom-cursor@alpha      # pnpm

Deno

Not yet supported.

Basic usage

Overriding the default cursor by a new one:

import { Cursor, useCursorStyleOnHover } from 'use-custom-cursor'

function TitleHovered() {
  return <h1 ref={useCursorStyleOnHover('Effect.Fill', 'Effect.Difference')}>Hover me!</h1>
}

function App() {
  return (
    <Cursor.Provider height="40px" width="40px" color="blue">
      <Cursor.Shape.Ring />
      <Cursor.Effect.Glow />
      <TitleHovered />
    </Cursor.Provider>
  )
}

Your cursor can be customized through a Style property which can have the following types:

string: when already defined as a default by the library, see Cursor.Shapes and Cursor.Effects for an exhaustive list
CSSProperties: when you want to manually customize the cursor
(props) => CSSProperties: when you want to customize the cursor depending of the context

Components

Cursor.Provider

Usage

Should be called at the root level of your application.

Returns

ReactNode containing every component that should rely on a custom cursor.

Props

Options	Type	Description
children	ReactNode	Everything that would benefit from the custom cursor should be there id
height	CSSProperties['height']	What's the expected height of your cursor
width	CSSProperties['width']	What's the expected width of your cursor
color	CSSProperties['color']	What's the color used when drawing your cursor
hideDefaultCursor	boolean	Define whether or not the default cursor should be hidden

Example

function CursorContainer(props: { children: ReactNode }) {
  return (
    <Cursor.Provider color="#91243E" height="25px" width="25px" hideDefaultCursor={false}>
      {children}
    </Cursor.Provider>
  )
}

Cursor.Shapes

Usage

You can find a list of default shapes provided by this library when you want to define a custom cursor. You just need to call the component in order to set the shape accordingly. Once the component is unmounted, the shape is unset from your cursor.

Available Shapes

Name	requirements	Description
Diamond	None	Will set the shape of the cursor to ◇
Mask	An `img` with an `svg` src as children	Will set the shape of the accordingly to the svg
Ring	None	Will set the shape of the cursor to ○
Square	None	Will set the shape of the cursor to □

Example

function CustomCursor() {
  return (
    <>
      <Cursor.Shape.Ring />
      <Cursor.Shape.Mask>
        <img src="myCustomShape.svg" alt="cursorShape" />
      </Cursor.Shape.Mask>
    </>
  )
}

Cursor.Effects

Usage

You can find a list of default effects provided by this library when you want to define a visual effect of your cursor unrelated to the shapes. You just need to call the component in order to set the effect accordingly. Once the component is unmounted, the effect is removed from your cursor.

Available Effects

Name	requirements	Description
Difference	None	Will inverse the color hovered by your cursor, works well when `Fill` is used to
Fill	None	Will fill the interior of the cursor with the color defined globally
Glow	None	Will make your cursor glow outside of its perimeter
Grow	None	Will enlarge your cursor
Zoom	An `img` as children	Will make your cursor zoom the image

Example

function CustomCursorEffects() {
  return (
    <>
      <Cursor.Effects.Glow />
      <Cursor.Effects.Grow />
      <Cursor.Effects.Zoom>
        <img src="avatar.png" alt="avatar" />
      </Cursor.Effects.Zoom>
    </>
  )
}

Hooks

useCursorStyle

Usage

Should be called when you want to apply a style to your cursor globally once the component where this hooks is called is mounted. The style will be removed once the component is unmounted. This hook can take as many Style as you need. When two arguments override the same property, the latter takes precedence.

Example

function Example() {
  useCursorStyle(
    'Shapes.Ring',
    'Effects.Glow',
    ({ color }) => ({ outline: `1px solid ${color}` }),
    { padding: '15px' },
  )

  return null
}

useCursorStyleOnHover

Usage

When you want to adapt your cursor when the user is specifically hovering an element. This hook can take as many Style as you need. When two arguments override the same property, the latter takes precedence.

Example

function ImageWithZoom(props: JSX.IntrinsicElements['img']) {
  const imageRef = useCursorStyleOnHover(
    'Shapes.Ring',
    'Effects.Grow',
    'Effects.Zoom',
    ({ color }) => ({ outline: `1px solid ${color}` }),
    { padding: '15px' },
  )

  return <img {...props} ref={imageRef} />
}

useGlobalStyle

Usage

When you want to get the global style for your cursor or when you want to modify them.

Example

function CustomCursor() {
  const { width, height } = useGlobalStyle({ color: 'green' })

  return <CustomCursorShape width={width} height={height} />
}

Alternatively, if you just want to modify the global style in an event, you can just call setGlobalStyle after importing it from the library.

useHideSystemCursor

Usage

When you don't want to hide the default cursor globally but just on some part of your application, you can use this hook to deactivate the cursor. It can optionaly take a target which will then ensure the default cursor is hidden only when hovering the target.

Example

function ImageWithZoom(props: JSX.IntrinsicElements['img']) {
  const imageRef = useCursorStyleOnHover('Effects.Zoom')
  useHideSystemCursor(imageRef)

  return <img {...props} ref={imageRef} />
}