use-custom-cursor v0.1.1

• Introduction
• Installation
  • Requirements
  • Node/npm
  • Deno
• Basic usage
• Components
  • Cursor.Provider
  • Cursor.Shapes
  • Cursor.Effects
• Hooks
  • useCursorStyle
  • useCursorStyleOnHover
  • useGlobalStyle
  • useHideSystemCursor

Introduction

This library is all about customizing the cursor with ease. This library has no other dependencies than react itself and polished. See the demo.

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 on="mount" />
      <Cursor.Effect.Glow on="hover" />
      <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

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. Depending of the component, you can specify whether the effect should be applied on mount or on hover (which then require children).

Available Shapes

Example

function CustomCursor() {
  return (
    <>
      <Cursor.Shape.Ring on="mount" />
      <Cursor.Shape.Mask on="hover">
        <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. Depending of the component, you can specify whether the effect should be applied on mount or on hover (which then require children).

Available Effects

Example

function CustomCursorEffects() {
  return (
    <>
      <Cursor.Effects.Glow on="mount" />
      <Cursor.Effects.Grow on="mount" />
      <Cursor.Effects.Zoom on="hover">
        <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} />
}

Related

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} />
}