Proteus Cursor
A shapeshifting cursor library Zero dependencies · TypeScript · < 20 KB

The cursor,
transfigured.

Named after Proteus, the old god of the sea who assumed every form — Proteus lets the pointer morph into dot, circle, fluid blob or text as it travels across your interface. Vanilla JS, with first-class adapters for React, Vue 3 and Svelte.

Try the shapes — hover, then look at your cursor
Fluid
a blob that stretches
Text
words under the pointer
Call to act
an invitation
v2.2.0 — latest release  ·  Magnetic parallax  ·  State-machine debug overlay  ·  Static reduced-motion fallback  ·  Adapters for React, Vue 3 & Svelte  ·  
I

Two modes. Infinite personality.

Every Proteus cursor starts from one of two base modes. Everything else — presets, states, animations — builds on top.

shape: 'circle'
Circle

A precise dot with an optional trailing shadow. Supports text, magnetism, blend modes. The classic — hover this plaque to feel it.

shape: 'fluid'
Fluid

A morphing blob that stretches and squeezes with velocity, like water finding its shape. Hover here and move quickly.

II

Start with a preset.

Five ready-made configurations, applied in one line: cursor.loadPreset('ghost'). Hover each entry to wear it.

i.
Ghost
Translucent circle — blends into any design.
ii.
Neon
Glowing halo, for dark creative sites.
iii.
Minimal
Tiny dot, no shadow. Zero visual noise.
iv.
Chrome
Blend-difference circle — inverts what it crosses.
v.
Ink
A fluid blob that stretches with movement.

The field is dark on purpose — every preset, ghost and chrome included, stays visible while you try it.

III

Every click, a choice.

Tactile feedback on every mousedown. Click inside each field to feel the difference.

'scale'
Scale
shrinks, then springs back
'ripple'
Ripple
a circle expands and fades
'none'
Stillness
no animation at all
IV

Pulled into place.

Hover the targets: the cursor is attracted to their centre and eases back when it leaves. With parallax, the element itself leans toward you.

magnetic: true
Constant full pull while hovering.
+ parallax
The element leans toward the cursor, then springs back.
radius: 140
Full pull at the centre, fading to none at 140 px.
V

The workshop.

Tune every parameter live — the cursor you are moving right now is the preview. Copy the generated code when it feels right.

Mode
Size 10px
Colour
Shadow
Shadow size 44px
Click animation
Blend mode
Cursor text
Magnetic
generated code 

          

          
The sandbox writes to the page cursor's default preset — hover states elsewhere on the page temporarily overlay it, then restore your settings.

        

      

    

  







  

    

    
VI

    

      
Up and running in sixty seconds.

      
Three steps. No build tools required. Works with any framework or vanilla HTML.


      

        

          
01 — Install

          
npm i proteuscursor

        

        

          
02 — Import

          
import ProteusCursor
  from 'proteuscursor';
import 'proteuscursor/style';

        

        

          
03 — Summon

          
const cursor =
  new ProteusCursor({
    shape: 'circle',
  });

        

      

    

  







  

    
The full account

    
Consult the
documentation.

    
API reference, the state machine, framework adapters, blend modes, accessibility — every option the library exposes, catalogued.

    Read the documentation →
  









Prologue