> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes.heygen.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulated Cursor

> A lightweight cursor pointer and click pulse for product walkthroughs and agent UI demos

export const InstallCommand = ({command}) => {
  const [copied, setCopied] = React.useState(false);
  const copy = async () => {
    try {
      if (navigator.clipboard && window.isSecureContext) {
        await navigator.clipboard.writeText(command);
      } else {
        const previous = document.activeElement;
        const scratch = document.createElement("textarea");
        scratch.value = command;
        scratch.setAttribute("readonly", "");
        scratch.style.position = "fixed";
        scratch.style.opacity = "0";
        document.body.appendChild(scratch);
        scratch.select();
        document.execCommand("copy");
        document.body.removeChild(scratch);
        previous?.focus?.();
      }
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    } catch {}
  };
  return <div className="hf-install-command not-prose my-4 flex items-stretch overflow-hidden rounded-xl border border-zinc-200 bg-zinc-50 dark:border-zinc-800 dark:bg-zinc-900">
      <code className="flex-1 overflow-x-auto whitespace-nowrap border-r border-zinc-200 px-4 py-3 font-mono text-sm text-zinc-800 dark:border-zinc-800 dark:text-zinc-100">
        {command}
      </code>
      <button type="button" onClick={copy} data-copied={copied ? "true" : "false"} aria-label={`Copy ${command} to the clipboard`} className="hf-install-copy">
        <svg className="hf-install-copy-clipboard" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 18 18" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
          <path d="M14.25 5.25H7.25C6.14543 5.25 5.25 6.14543 5.25 7.25V14.25C5.25 15.3546 6.14543 16.25 7.25 16.25H14.25C15.3546 16.25 16.25 15.3546 16.25 14.25V7.25C16.25 6.14543 15.3546 5.25 14.25 5.25Z" />
          <path d="M2.80103 11.998L1.77203 5.07397C1.61003 3.98097 2.36403 2.96397 3.45603 2.80197L10.38 1.77297C11.313 1.63397 12.19 2.16297 12.528 3.00097" />
        </svg>
        <svg className="hf-install-copy-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 18 18" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
          <path d="M2.75 9.5L6.5 13.25L15.25 4.5" />
        </svg>
      </button>
      <span className="hf-install-copy-status" role="status" aria-live="polite">
        {copied ? "Copied" : ""}
      </span>
    </div>;
};

<iframe className="w-full aspect-video rounded-xl border-0 bg-zinc-100 dark:bg-zinc-800" title="simulated-cursor preview" loading="lazy" srcDoc={`<!doctype html><html><head><meta charset="utf-8"><style>html,body{margin:0;height:100%;overflow:hidden;background:transparent}hyperframes-player{display:block;width:100%;height:100%}</style><script src="https://cdn.jsdelivr.net/npm/@hyperframes/player@0.7/dist/hyperframes-player.global.js"><\/script></head><body><script>fetch("/public/catalog/components/simulated-cursor.json").then(function(r){return r.json()}).then(function(d){var p=document.createElement("hyperframes-player");p.setAttribute("srcdoc",d.html);p.setAttribute("controls","");p.setAttribute("autoplay","");p.setAttribute("loop","");p.setAttribute("muted","");p.setAttribute("poster","https://static.heygen.ai/hyperframes-oss/docs/images/catalog/components/simulated-cursor.png");document.body.appendChild(p)});<\/script></body></html>`} />

## Install

<InstallCommand command="npx hyperframes add simulated-cursor" />

That writes one file: `compositions/components/simulated-cursor.html`.

## Variables

Every one of these has a default, so the piece works untouched. Set the ones you
want to change on the element:

| Variable | Default    | Accepts                              | What it does                                                                                                                                                                    |
| -------- | ---------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size`   | `44`       | 20px to 120px, step 2px              | Height and width of the pointer in pixels. The click ring scales with it. Values outside the range clamp to the nearest end and anything that is not a number falls back to 44. |
| `tone`   | `light`    | `light`, `dark`, `accent`            | Pointer fill and click ring colour: light reads on dark screens, dark reads on light ones, accent rides --hf-ui-accent.                                                         |
| `pulse`  | `standard` | `subtle`, `standard`, `bold`, `none` | Weight of the ring the click animation expands: subtle is a thin small ring, bold a thick wide one, none removes the ring entirely.                                             |

Set them with `data-variable-values` on the element that mounts it. These are the
defaults, so this behaves exactly like the preview above until you change one:

```html wrap theme={null}
<div
  data-composition-id="simulated-cursor"
  data-composition-src="compositions/components/simulated-cursor.html"
  data-variable-values='{"size":44,"tone":"light","pulse":"standard"}'
></div>
```

## Source

<Accordion title={`simulated-cursor.html`}>
  ```html theme={null}
  <!--
    Simulated Cursor - pointer and click pulse primitive.

    Paste the markup, CSS and script once, then animate .hf-simulated-cursor
    with x/y values in your paused GSAP timeline. Trigger the click pulse by
    scaling/fading .hf-simulated-cursor-pulse.

    Variables. The script reads each one, falls back to the declared default on
    anything missing or invalid, and writes the result as a custom property the
    CSS above consumes. The timeline recipe below is untouched by them: it keeps
    driving the pointer position and the ring scale and fade.

      - size (number 20 to 120, step 2, unit px, default 44): height and width of
        the pointer. The click ring, its offset and its border scale with it, so
        the tip stays anchored at the animated x/y. Values below 20 clamp to 20,
        values above 120 clamp to 120, and anything that is not a number falls
        back to 44.
      - tone (light | dark | accent, default light): pointer fill, outline and
        ring colour. light is the white pointer with a dark outline for dark
        screens, dark flips both for light screens, accent rides --hf-ui-accent.
      - pulse (subtle | standard | bold | none, default standard): weight of the
        click ring. subtle is thin and small, bold thick and wide, none removes
        the ring entirely. The ring stays centred on the same point in every
        case, and it is only on screen while the click animation runs.

    On every default the result is identical to the original: a 44px white
    pointer with a 22px, 2px white ring offset 9px from the tip.
  -->

  <div
    class="hf-simulated-cursor"
    aria-hidden="true"
    data-composition-variables='[
      {"id": "size", "type": "number", "role": "layout", "label": "Size", "description": "Height and width of the pointer in pixels. The click ring scales with it. Values outside the range clamp to the nearest end and anything that is not a number falls back to 44.", "default": 44, "min": 20, "max": 120, "step": 2, "unit": "px"},
      {"id": "tone", "type": "enum", "role": "style", "label": "Tone", "description": "Pointer fill and click ring colour: light reads on dark screens, dark reads on light ones, accent rides --hf-ui-accent.", "default": "light", "options": [{"value": "light", "label": "Light"}, {"value": "dark", "label": "Dark"}, {"value": "accent", "label": "Accent"}]},
      {"id": "pulse", "type": "enum", "role": "style", "label": "Click ring", "description": "Weight of the ring the click animation expands: subtle is a thin small ring, bold a thick wide one, none removes the ring entirely.", "default": "standard", "options": [{"value": "subtle", "label": "Subtle"}, {"value": "standard", "label": "Standard"}, {"value": "bold", "label": "Bold"}, {"value": "none", "label": "None"}]}
    ]'
  >
    <div class="hf-simulated-cursor-pulse"></div>
    <svg viewBox="0 0 24 24" width="44" height="44">
      <path
        d="M3 2.8 20.6 14 12.8 15.5 9 22 3 2.8Z"
        fill="white"
        stroke="rgba(0,0,0,0.45)"
        stroke-width="1.4"
      />
    </svg>
  </div>

  <style>
    .hf-simulated-cursor {
      position: absolute;
      left: 0;
      top: 0;
      width: calc(44px * var(--hf-cursor-scale, 1));
      height: calc(44px * var(--hf-cursor-scale, 1));
      transform: translate3d(var(--hf-cursor-x, 0px), var(--hf-cursor-y, 0px), 0);
      pointer-events: none;
      z-index: 999;
      filter: drop-shadow(0 8px 18px rgba(0, 0, 0, 0.24));
    }
    .hf-simulated-cursor svg {
      width: 100%;
      height: 100%;
    }
    .hf-simulated-cursor svg path {
      fill: var(--hf-cursor-fill, #ffffff);
      stroke: var(--hf-cursor-edge, rgba(0, 0, 0, 0.45));
    }
    .hf-simulated-cursor-pulse {
      display: var(--hf-cursor-ring-display, block);
      position: absolute;
      left: calc((20px - var(--hf-cursor-ring-size, 22px) / 2) * var(--hf-cursor-scale, 1));
      top: calc((20px - var(--hf-cursor-ring-size, 22px) / 2) * var(--hf-cursor-scale, 1));
      width: calc(var(--hf-cursor-ring-size, 22px) * var(--hf-cursor-scale, 1));
      height: calc(var(--hf-cursor-ring-size, 22px) * var(--hf-cursor-scale, 1));
      border: calc(var(--hf-cursor-ring-width, 2px) * var(--hf-cursor-scale, 1)) solid
        var(--hf-cursor-ring, rgba(255, 255, 255, 0.85));
      border-radius: 999px;
      opacity: 0;
      transform: scale(0.2);
    }
  </style>

  <script>
    (function () {
      "use strict";

      var vars =
        window.__hyperframes && window.__hyperframes.getVariables
          ? window.__hyperframes.getVariables()
          : {};

      // Unrecognised or out-of-range overrides return to their declared defaults.
      function pick(table, value, fallback) {
        return Object.prototype.hasOwnProperty.call(table, value) ? value : fallback;
      }

      var tones = {
        light: { fill: "#ffffff", edge: "rgba(0, 0, 0, 0.45)", ring: "rgba(255, 255, 255, 0.85)" },
        dark: { fill: "#18181b", edge: "rgba(255, 255, 255, 0.75)", ring: "rgba(24, 24, 27, 0.75)" },
        accent: {
          fill: "var(--hf-ui-accent, #3ce6ac)",
          edge: "rgba(0, 0, 0, 0.45)",
          ring: "var(--hf-ui-accent, #3ce6ac)",
        },
      };
      var pulses = {
        subtle: { size: "18px", width: "1px", display: "block" },
        standard: { size: "22px", width: "2px", display: "block" },
        bold: { size: "28px", width: "3px", display: "block" },
        none: { size: "22px", width: "2px", display: "none" },
      };

      var size = typeof vars.size === "number" ? vars.size : parseFloat(vars.size);
      if (!isFinite(size)) size = 44;
      size = Math.min(120, Math.max(20, size));

      var tone = tones[pick(tones, vars.tone, "light")];
      var pulse = pulses[pick(pulses, vars.pulse, "standard")];

      var roots = document.querySelectorAll(".hf-simulated-cursor");
      for (var i = 0; i < roots.length; i += 1) {
        var root = roots[i];
        root.style.setProperty("--hf-cursor-scale", String(size / 44));
        root.style.setProperty("--hf-cursor-fill", tone.fill);
        root.style.setProperty("--hf-cursor-edge", tone.edge);
        root.style.setProperty("--hf-cursor-ring", tone.ring);
        root.style.setProperty("--hf-cursor-ring-size", pulse.size);
        root.style.setProperty("--hf-cursor-ring-width", pulse.width);
        root.style.setProperty("--hf-cursor-ring-display", pulse.display);
      }
    })();
  </script>

  <!--
    Timeline integration:

    tl.to(".hf-simulated-cursor", { "--hf-cursor-x": "760px", "--hf-cursor-y": "420px", duration: 0.8, ease: "power2.inOut" }, startTime);
    tl.fromTo(".hf-simulated-cursor-pulse", { opacity: 0.8, scale: 0.2 }, { opacity: 0, scale: 2.4, duration: 0.45, ease: "power2.out" }, startTime + 0.8);
  -->
  ```
</Accordion>

## Usage

Open `compositions/components/simulated-cursor.html` and paste its contents into your composition. See the comment header in the file for detailed instructions.

Tagged `video-primitive` `motion-primitive` `cursor` `ui` `walkthrough`.

## Related topics

* [Browse the complete Catalog](/catalog)
* [Add assets and Catalog items in Studio](/studio/assets-and-blocks)
* [Build a richer composition](/go-further)


## Related topics

- [Multiplayer Cursors](/catalog/components/multiplayer-cursors.md)
- [Oversized Cursor](/catalog/components/oversized-cursor.md)
- [VFX Text Cursor](/catalog/blocks/vfx-text-cursor.md)
