Cursor Display

An animated cursor highlight effect that follows your mouse and morphs to highlight interactive elements. This creates a polished, modern UI feel that provides visual feedback as users navigate your interface.

⚠️ Single Provider Pattern: Use one CursorProvider at the top level of your cursor-enabled area. Multiple providers create multiple cursors.

// ✅ Good - Single provider
<CursorProvider>
  <Section1 />
  <Section2 />
</CursorProvider>

// ❌ Bad - Multiple cursors
<CursorProvider><Section1 /></CursorProvider>
<CursorProvider><Section2 /></CursorProvider>

How It Works

The cursor display system consists of:

CursorProvider - A wrapper component that tracks mouse position and renders the animated cursor overlay
Pre-built components - CursorButton, CursorInputRoot, CursorSelectTrigger, CursorTextarea that automatically register with the cursor context
withCursor HOC - A Higher-Order Component to add cursor highlighting to any custom component

Basic Example

Hover over the interactive elements below to see the cursor highlight effect.

Buttons

Input

Select

Textarea

Using withCursor HOC

The withCursor Higher-Order Component lets you add cursor highlighting to any component. This is useful when you want the cursor effect on custom components like Cards, Links, or any interactive element.

Custom components wrapped with withCursor

Cursor Card

This Card component is wrapped with withCursor

Interactive

Another Card

Hover to see the cursor highlight effect

Hover me

Even a plain div can be enhanced with cursor effects!

How withCursor Works

import { withCursor } from '@vuer-ai/vuer-uikit';

// Wrap a component
const CursorCard = withCursor(Card);

// Use it inside a CursorProvider
<CursorProvider>
  <CursorCard>Hover me!</CursorCard>
</CursorProvider>

The HOC:

Tracks onMouseEnter, onMouseMove, and onMouseOut events
Calculates the visible portion of the element (handles scrollable containers)
Registers/unregisters the element with the cursor context
Preserves forwarded refs and original event handlers

Full Page Layout Example

A comprehensive example showing how cursor display enhances a settings page with navigation, forms, and various interactive elements.

Profile

Notifications

Security

Appearance

Profile Settings

Manage your account information

Display Name

Bio

Timezone

CursorProvider Props

Prop	Type	Default	Description
`maxOffsetX`	`number`	`5`	Maximum horizontal offset when cursor is near element edge
`maxOffsetY`	`number`	`20`	Maximum vertical offset when cursor is near element edge
`cursorSize`	`number`	`20`	Size of the cursor dot when not hovering an element
`boundaryThreshold`	`number`	`4`	Distance from element edge (inside) before offset begins
`outerThreshold`	`number`	`8`	Distance outside element before offset reaches maximum
`cursorClassName`	`string`	-	Additional CSS classes for the cursor element
`className`	`string`	-	CSS classes for the provider wrapper
`as`	`ElementType`	`"div"`	The element type to render as the wrapper

Available Components

Component	Description
`CursorProvider`	Wrapper that enables cursor tracking and renders the overlay
`CursorButton`	Button with cursor highlighting
`CursorInputRoot`	Input field with cursor highlighting
`CursorSelectTrigger`	Select trigger with cursor highlighting
`CursorTextarea`	Textarea with cursor highlighting
`withCursor`	HOC to add cursor highlighting to any component

Best Practices

Wrap at the right level - Place CursorProvider around the area where you want the cursor effect. It can be a whole page or just a specific section.
Use pre-built components - For common UI elements, use the pre-built Cursor* components for consistency.
Custom components - Use withCursor for cards, navigation items, or any custom interactive elements.
Consider scrollable containers - The cursor system automatically handles elements inside scrollable containers by calculating the visible portion.
Performance - The cursor uses position: fixed and CSS transitions for smooth performance. The overlay is portaled to document.body to avoid layout issues.