Skip to main content

API Reference

The Widget API allows you to create custom, interactive objects that extend the functionality of Figma design files and FigJam boards. You’ll likely use both the widget API and plugin API when building widgets.

  • Widget API: defines the custom object and how people can interact with it
  • Plugin API: access external resources or manipulate other nodes in the file

The Widget API is a component-based API similar to React. It gives you access to the tools you need to build a widget node on the canvas that responds to a variety of interactions.

There are three main aspects of the Widget API: components, functions, and hooks. Together they control rendering the widget in a file and managing its state as you interact with it.

If you’ve used the Plugin API, you’ll already be familiar with the figma global object. You can access the Widget API from that same figma object, via figma.widget.

Components

Components are the layers you’ll use to build your custom interactive widget. You can think of them as building blocks.

Each component supports a range of properties, which you can use to customize their appearance. Some properties are shared across components and some are unique to specific components.

There are components based on layers or node types you can already find and use in files:

There are three other components available that aren’t based on layers:

  • Input: allows you to make a text component editable. This makes it possible for people to input or update text components within the widget.
  • Fragment: allows you to render children without having to group them in a parent node. You can’t pass properties to a fragment.
  • Span: allows you to style ranges of text inside of a Text component.

Functions

Functions are statements or blocks of code that perform a specific task. Functions accept parameters and other data as input and return a related output. There are only two functions defined in the Widget API:

  • register: the main entry point for rendering a widget. This function expects a widget function that describes your widget and returns the widget node made up of the components we mentioned above.
  • waitForTask: this function enables asynchronous work, such as data fetching. It accepts a promise and only terminates when that promise resolves.
  • colorMapToOptions: this function is called on a color palette defined in figma.constants.colors.*, and returns WidgetPropertyMenuColorSelectorOption[].

Hooks

Hooks are a specific type of function. They allow you to reuse state-based logic or behavior across your components. You can identify hooks by their use prefix.

  • useEffect: this hook can run any time the widget’s state changes. It allows you to perform asynchronous tasks, bundle calls, or consolidate the side-effects of event handlers.
  • usePropertyMenu: this hook allows you to define an interactive property menu that displays when the widget is selected.
  • useStickable: this FigJam only hook allows your widget to be stuck to other nodes in the file. This is similar to how stamps work in FigJam files.
  • useStickableHost: this FigJam only hook allows other nodes in the file to stick to your widget.
  • useSyncedState: this hook declares that rendering your widget relies on a changeable state. You give this hook a key and default value, which you can use and update across different states.
  • useSyncedMap: this hook also allows you to manage widget state. You can give this hook multiple keys and values and update widget state based on changes to individual values, not the entire map. This allows you to accurately render widget state when multiple people interact with a widget at once.
  • useWidgetId: this hook allows you to reference a currently active widget. It returns a unique id which allows you to reference that WidgetNode in the Plugin API.

Destructure globals

We recommend destructuring components, hooks, and functions at the beginning of your widget code. This saves you from having to reference each of these components by their qualified names, such as figma.widget.AutoLayout.

const { widget } = figma
const {
  // Components
  AutoLayout,
  Frame,
  Text,
  Input,
  Rectangle,
  Image,
  SVG,
  Ellipse,
  Line,
  Fragment,

  // Hooks
  useSyncedState,
  useSyncedMap,
  usePropertyMenu,
  useEffect,
  useStickable,
  useStickableHost,
  useWidgetId,

  // Functions
  register,
  waitForTask
} = widget

In our sample counter widget, we’ve done this to figma.widget as well as the individual hooks (useSyncedState and usePropertyMenu) and components (AutoLayout, Text, SVG) we’ll use in our widget code:

const { widget } = figma
const { useSyncedState, usePropertyMenu, AutoLayout, Text, SVG } = widget

On this page