# Cursor (Moonarc) A custom pointer that trails the real one: a dot, a ring that grows over links and buttons, or a label ("View") any element can ask for with data-cursor-label. One fixed element; the script writes the position and a state, CSS transitions the lag, the growth and the pill on the preset curve. Not installed on touch or under reduced motion. - Import: `import Cursor from '@moonarc/core/Cursor'` - Install: `npx astro add moonarc` · copy-paste: `npx shadcn@latest add https://moonarc.dev/r/cursor.json` - Tier B · category pointer · trigger pointer - Readout: `` - Browser support: widely (every browser) - Measured cost: 1021 B raw JS · 574 B gzip · + runtime (with dependencies 2.7 kB raw; CSS 6.0 kB raw) - Page: https://moonarc.dev/components/cursor/ ## Props | Prop | Type | Default | Description | |---|---|---|---| | `mode` | `'dot' | 'ring' | 'label'` | `'ring'` | dot: a small disc · ring: grows over targets · label: becomes a pill with text over targets that carry data-cursor-label, grows over the rest. | | `size` | `number` | `12` | Disc diameter in px. | | `grow` | `number` | `3` | Growth over targets, as a multiple of size. | | `blend` | `boolean` | `false` | mix-blend-mode: difference, so the disc inverts what it covers. Off by default: on a light theme a light disc disappears. | | `hideNative` | `boolean` | `false` | Hide the native cursor while the custom one is live, everywhere except over text fields. | | `within` | `boolean` | `false` | Confine to the parent element: positioned inside it, pointer read from it only, hidden when the pointer leaves it. | | `label` | `string` | `'View'` | Text for targets that carry data-cursor-label with no value. | ## Usage ```astro

…

``` ## Reduced motion Not installed: the element is hidden and the script never binds, so the native cursor is the only one. Switched on while the page is open (or through the page's own motion switch), the disc hides and hideNative gives the native cursor back. ## With ClientRouter Bound through the shared runtime: the listeners are aborted before the swap and the cursor returns to its hidden state, which ends hideNative (a :has() rule on that state, nothing written to ); the next page binds its own. ## Craft - The lag is a CSS transition on translate, on the fast token and the exit curve: close enough to feel attached, late enough to read as a trail. No lerp runs in JavaScript, so the follow costs one style write per move. - Targets are found by one pointerover listener on the document (or the host) through closest(), never a listener per element, so a page with three hundred links pays nothing per link. - Over input, textarea, select and contenteditable the custom cursor hides: the I-beam is information the ring would cover. - Never installed where (hover: hover) and (pointer: fine) do not both hold, and never under reduced motion. On a phone, a custom cursor would be a stuck dot. - pointerout with no relatedTarget means the pointer left the window; the cursor hides rather than freezing at the edge. ## Replaces - SplashCursor / BlobCursor (React Bits) - FollowerPointerCard (Aceternity) - Cursor (Motion Primitives) - SmoothCursor (Magic UI) ## Source ```astro --- /** * Cursor — a custom pointer that trails the real one and reacts to what it * is over: a dot, a ring that grows on links and buttons, or a label * ("View") that any element can ask for with data-cursor-label. * * One fixed element. The script writes the pointer position as two custom * properties and one state attribute; the lag, the growth and the label * morph are CSS transitions on the preset's curve, so the follow has the * same character as everything else on the page and no lerp runs in JS. * Targets are delegated: one pointerover listener on the document reads * `a, button, [data-cursor]`, never a listener per element. Not installed on * touch, coarse pointers or reduced motion; hidden over text fields so the * native I-beam does its job; gone when the pointer leaves the window. * `within` confines it to the parent element (a section, a card, a demo); * hideNative is a :has() rule on the state, so the script never touches . */ import type { HTMLAttributes } from 'astro/types'; interface Props extends HTMLAttributes<'div'> { /** dot: a small disc · ring: a disc that grows over targets · label: a disc that becomes a pill with text over labelled targets (and grows over the rest). */ mode?: 'dot' | 'ring' | 'label'; /** Disc diameter in px. */ size?: number; /** Growth over targets, as a multiple of size. */ grow?: number; /** mix-blend-mode: difference — inverts what it covers. Reads badly on a light theme unless the disc is dark. */ blend?: boolean; /** Hide the native cursor everywhere except over text fields. */ hideNative?: boolean; /** Confine to the parent element: positioned absolutely inside it, pointer read from it only. */ within?: boolean; /** Default label text for mode="label" when a target has data-cursor-label without a value. */ label?: string; } const { mode = 'ring', size = 12, grow = 3, blend = false, hideNative = false, within = false, label = 'View', class: className, style, ...rest } = Astro.props; const inline = [`--ma-cursor-size:${size}px`, `--ma-cursor-grow:${grow}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';'); --- ```