Figma Widgets: Live Apps on Your Canvas

WHY IT EXISTS To provide persistent, collaborative tools directly on the Figma canvas. Plugins are single-user and ephemeral; widgets are multi-user and part of the document itself, enabling shared, stateful interactions for things like voting or project planning.

THE MENTAL MODEL A widget is a React component for your Figma canvas. You write TypeScript and JSX to define an interactive object that everyone in the file can see and use simultaneously. It's a shared tool living on the board, not a personal script running in a modal.

HOW IT WORKS You build a widget using Figma's API, which is based on TypeScript and JSX. You define its UI using a combination of components that map to Figma layers like frames, text, and shapes. The widget function renders these components inside a dedicated object on the canvas. It can also access the Plugin API to fetch external data or modify other parts of the file.

WHEN TO USE IT Use widgets for tools that require real-time collaboration and a persistent state on the canvas. Good examples include: gathering team feedback with a live poll, displaying data from an external source in an interactive table, or managing tasks on a shared project timeline.

WHEN NOT TO USE IT For single-user, temporary tasks, a plugin is a better choice. If the tool doesn't need to be a visible, persistent object on the canvas for everyone to see and interact with, a widget adds unnecessary complexity. For example, a script that just renames layers for one user is a plugin, not a widget.

ONE CANONICAL EXAMPLE A common footgun is poor performance in large files. By default, a widget loads the entire document when it runs, which can cause a 20-30 second delay. To fix this, you must add "documentAccess": "dynamic-page" to the widget's manifest file. This tells Figma to only load the specific pages the widget needs on-demand, preventing the initial freeze and making the experience much faster for users.