CSS Variables And Events

StringCursor exposes two different output surfaces:

• CSS variables written to targets and portals
• emitted events for target activity and global cursor motion

Target Variables

On elements marked with string="cursor" the runtime always writes:

• --x
• --y

These are normalized local coordinates.

Alignment modes:

• start: 0 .. 1
• center: roughly -1 .. 1
• end: -1 .. 0

Extra Target Variables

If string-cursor-vars enables them, the runtime can also write:

• --x-px
• --y-px
• --dx
• --dy
• --angle
• --angle-deg

Supported names are parsed case-insensitively and can be separated with , or |.

Example:

<button string="cursor" string-cursor-vars="xpx|ypx|dx|dy|angle-deg">Hover</button>

Portal Variables

On string-cursor="..." portals the runtime writes:

• --x
• --y
• --x-lerp
• --y-lerp

Important difference:

• target --x and --y are normalized local values
• portal --x and --y are viewport pixel positions

So a portal usually consumes them like this:

transform: translate3d(calc(var(--x, 0) * 1px), calc(var(--y, 0) * 1px), 0) translate(-50%, -50%);

Target Events

The module emits these target-scoped events:

• cursor:start:<id>
• cursor:move:<id>
• cursor:pixel:<id>
• cursor:end:<id>

Payloads:

• cursor:start:<id>: null
• cursor:move:<id>: { x, y }
• cursor:pixel:<id>: { x, y }
• cursor:end:<id>: null

cursor:move is based on normalized local coordinates. cursor:pixel is based on element-local pixel coordinates.

Global Cursor Event

If at least one portal exists, StringCursor also emits a global event:

• cursor

Payload:

{
  x,
  y,
  stepX,
  stepY,
}

This is useful when you want to build global cursor-reactive behavior without listening to a particular target ID.

Portal Classes

In addition to CSS variables, the runtime toggles:

• -show on portals
• the class from string-cursor-class while the linked target is hovered