Skip to main content

How Widgets Run

Widgets run inside the same sandbox as Plugins but with the additional ability to:

  • Create a custom object that lives on the canvas
  • Respond to user interactions on these custom objects

Widgets only run in response to user interaction and only on the specific client that initiated this interaction. All other clients will see the updated widget via regular updates to the file, via Multiplayer.

As pictured above, it is helpful to think about Widget Code in 2 distinct parts:

  1. Rendering Code that describes how a widget should look
  2. State Updating Code that updates widget state

Rendering Code

Code that describes how a widget should look runs synchronously and should solely depend on a widget’s state in order to avoid inconsistencies when rendering across multiple clients. For instance, a widget shouldn’t depend on attributes of other nodes on the canvas when deciding how it looks.

If you want to use something like figma.activeUsers in your widget, the recommended pattern is to use a lazy default initializer to initialize a synced state value.

This will be enforced at the API level - widget rendering code won’t be able to read and access data outside of the particular widget’s state.

State Updating Code

Code that updates widget state runs asynchronously and can do much more than read the widget state. It will have full read/write access to the document via the Plugin API. Code here can also make network requests via iframes and open iframes to get more user input. Most commonly, code here ends up updating the widget state, which will cause the widget to re-render.