Building Custom Figma Widgets with the Widget API

WHY IT EXISTS: To extend Figma's functionality beyond static design. It allows developers to create custom, interactive, and stateful objects that live directly on the canvas, unlike plugins which are often ephemeral tools. This enables richer collaboration and custom workflows in design files and FigJam boards.

THE MENTAL MODEL: Think of the Widget API as a specialized, mini-React for the Figma canvas. You define a UI with components, manage its state with hooks, and handle its lifecycle with functions. It's about building persistent, interactive nodes, not just running a one-off script.

HOW IT WORKS: The API, accessed via figma.widget, is built on three pillars. First, Components are the visual building blocks, like AutoLayout, Text, and Rectangle, plus special ones like Input for editable text. Second, Functions are the core actions; register is the main entry point that renders your widget, and waitForTask handles asynchronous operations. Third, Hooks manage state and side effects, identified by their use prefix. Key hooks include useEffect for running code when state changes and useSyncedState or useSyncedMap for managing state that needs to sync between multiple users in real-time.

WHEN TO USE IT: Use the Widget API to create objects that need to be interactive and persistent on the canvas. This is ideal for collaborative tools like a voting system, a countdown timer, a simple poll, or a custom sticky note. It's the right choice when the tool is part of the canvas content.

WHEN NOT TO USE IT: Don't use the Widget API for one-off, "fire and forget" scripts that manipulate the document. For tasks like batch-renaming layers, generating a color palette, or exporting assets in a specific format, the standard Plugin API is the more appropriate tool. Widgets are for interactive objects that remain on the canvas, not for transient user scripts.

ONE CANONICAL EXAMPLE: A simple counter widget. It would use an AutoLayout component to hold a Text component displaying the count and two SVG components for plus and minus buttons. The count itself would be managed by useSyncedState('count', 0), ensuring that if one user clicks plus, the count updates for everyone viewing the widget. The register function would wrap this entire structure to render it on the canvas.