@useclickly/react

Click-to-annotate dev toolbar for React. Generates prompts your AI coding agent can actually act on.

Drop <Clickly /> into your React app (dev only). A small floating action button appears in the bottom-right corner. Open it, click any element, write a comment — copy a perfectly-formatted markdown prompt into Claude Code, Cursor, Codex, or any MCP-aware tool.

Install

npm install -D @useclickly/react
# or:
pnpm add -D @useclickly/react
yarn add -D @useclickly/react

Use

import { Clickly } from "@useclickly/react";

export default function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === "development" && <Clickly />}
    </>
  );
}

That's it. The component returns null on the server (safe under SSR / Next App Router) and ships with "use client" already baked into the bundle.

What it does

| Mode | How | |---|---| | Single | Click any element → popup with comment box | | Multi-select | Press 2 or shift-click to pin elements, hit Annotate (N) when done | | Area drag | Press 3, drag a rectangle, every intersecting element gets pinned | | Draw | Press 4 to sketch freehand strokes — saved as AFS stroke annotations | | Layout mode | Press L for a component palette + section-rearrange overlay. Optional wireframe sub-mode fades the page so you can sketch a fresh layout. | | Animation pause | Press P to freeze CSS / WAAPI / GSAP / videos for annotating a specific frame | | Persistent pins | Annotated elements stay numbered on the page across page interactions | | Auto-copy | Submitting an annotation copies markdown to clipboard (toggleable) | | Settings | Output detail tier, React component info, marker colour — all in the gear menu |

What gets captured

For every selected element, Clickly automatically collects:

• Short + full CSS selector (section.hero > button.cta)
• Computed styles (curated by detail tier)
• Bounding box + position (handles fixed / sticky)
• ARIA / role / tabindex / title
• Visible nearby text (truncated)
• React component tree (App > Dashboard > Button) via Fiber walk
• Source file + line (src/Button.tsx:42) on Vite/Next — instant grep target

Keyboard shortcuts

| Key | Action | |---|---| | ⌘/Ctrl + Shift + F | Toggle the toolbar | | 1 / 2 / 3 / 4 | Switch mode (single / multi / area / draw) | | L | Toggle layout mode (palette + section rearrange) | | P | Pause / resume page animations | | Enter | Open the popup with all pinned elements | | Esc | Cancel popup · cancel a layout drag · clear pins · or collapse toolbar | | C | Copy all annotations as markdown | | X | Clear all annotations |

Props

All optional; <Clickly /> works with zero config.

interface ClicklyProps {
  className?: string;
  endpoint?: string;          // MCP server URL — see @useclickly/mcp-server
  sessionId?: string;
  onAnnotationAdd?: (id: string) => void;
  onAnnotationDelete?: (id: string) => void;
  onAnnotationsClear?: () => void;
  onCopy?: (markdown: string) => void;
  onSessionCreated?: (sessionId: string) => void;
}

Output

## Annotation #1
**Element:** `button.cta.primary`
**Path:** `body > main > section.hero > button.cta.primary`
**Position:** 120px, 480px (200×48px)
**Source:** `src/components/Hero.tsx:42`
**React:** App > LandingPage > HeroSection > CTAButton
**Feedback:** Button is cut off on mobile viewport

Configurable via the settings popover: compact (one-liner) → standard → detailed → forensic (full computed styles).

The shape is AFS 1.1-compatible — every MCP-aware agent can parse it.

Requirements

• React 18+ or 19+
• Browser environment (no SSR; component returns null server-side)
• Desktop only — touch / mobile is not optimised
• Not for React Native — see the main README

Advanced

For framework-agnostic engine access — building your own UI on top of Clickly's selection + metadata — see @useclickly/core.

For agent integration over MCP — your agent reading/responding to annotations directly — see @useclickly/mcp-server.

License

MIT