figma-plugin-react-hooks

Use Figma selection in your plugin UI via React hooks.

Supports TypeScript.

Usage

npm install figma-plugin-react-hooks

You need to import the package in your plugin logic for the React hooks to work, as it sets up the other end of the communication pipeline.

plugin.ts (plugin logic):

// Set up change handlers
import 'figma-plugin-react-hooks';

You can then use the hook in React like any other hook. Note the import from figma-plugin-react-hooks/hook.

React app (plugin UI):

import { FC } from 'react';

import useFigmaSelection from 'figma-plugin-react-hooks/hook';

const SomeComponent: FC = () => {
  const [selection] = useFigmaSelection();

  // Do something with the selection, e.g. display node names
  return <div>{selection.map((node) => node.name).join(', ')}</div>;
};

export default SomeComponent;

Hook options

The hook can be configured by passing an options object to the hook call.

Important: only one set of options will take presence in the hook. Whichever hook is the most recent to be mounted will override previous options.

It is best to create the hook options as a constant that is imported into each of the files where the hook is used.

constants.ts:

import { FigmaSelectionHookOptions } from 'figma-plugin-react-hooks/hook';

// Using satisfies gives you type hints and autocomplete while retaining the exact inferred return type from the hook
export const selectionHookOptions = {
  resolveProperties: ['name', 'boundVariables', 'absoluteBoundingBox', 'visible']
  resolveChildrenNodes: true
} satisfies FigmaSelectionHookOptions;

React app:

import { FC } from 'react';

import useFigmaSelection from 'figma-plugin-react-hooks/hook';

import { selectionHookOptions } from './constants';

const SomeComponent: FC = () => {
  const [selection] = useFigmaSelection(selectionHookOptions);

  ...
};

Performance

The more nodes the users selects and the more properties you want to resolve from the nodes, the worse the performance will be. If you're resolving all node properties and children, the execution time will easily get to several seconds and beyond. Do your best to only resolve the properties you need to keep the performance at an acceptable level.

Type utilities

The library also exports a few utility types for you to use in your React components:

import { FC } from 'react';

import { FigmaSelectionHookNode } from 'figma-plugin-react-hooks/hook';

// Your custom options
import { figmaSelectionHookOptions } from './constants';

// FigmaSelectionHookNode is the type of a single node returned from the hook, inferred from the options you pass to it
interface NodeListItemProps {
  node: FigmaSelectionHookNode<typeof figmaSelectionHookOptions>;
}

const NodeListItem: FC<NodeListItemProps> = ({ node }) => {
  ...
};

Caveat

The hook is based on Figma's selectionchange and nodechange events, which currently do not support all changes in the selection. Examples of missing events:

• Binding a text variable to a node
• Using "reset all changes" on a Component instance

Types

RPCOptions

Ƭ RPCOptions: Object

Type declaration

| Name | Type | Description | | :------ | :------ | :------ | | timeoutMs? | number | Timeout in milliseconds Default: 3000 | | pluginId? | string | If your plugin UI is hosted (non-null origin), pluginId must be defined to allow messages to be sent | | logicTargetOrigin? | string | Specifies what the origin of the plugin UI must be for a message to be dispatched from plugin logic to UI If defined, add http://localhost:<port> to this field in your local environment to allow messaging while running on a dev server Default: '*' | | uiTargetOrigin? | string | Specifies what the origin of the plugin logic must be for a message to be dispatched from UI to plugin logic Usually 'https://www.figma.com' Default: '*' |

OptSceneNodeProperties

Ƭ OptSceneNodeProperties: readonly SceneNodePropertyKey[] | "all"

BoundVariableKey

Ƭ BoundVariableKey: keyof NonNullable<SceneNode["boundVariables"]>

OptSceneNodeVariables

Ƭ OptSceneNodeVariables: readonly BoundVariableKey[] | "all"

OptSharedPluginDataKeys

Ƭ OptSharedPluginDataKeys: Record<string, string[]>

FigmaSelectionHookOptions

Ƭ FigmaSelectionHookOptions: Object

Use satisfies (for TS >= 4.9) with this type to allow for type checking the options object while the type of the object remains exact.

This allows the hook to infer the type of the returned nodes correctly.

Example:

const options = {
  nodeTypes: ['TEXT', 'FRAME'],
  resolveProperties: ['name', 'characters', 'children']
} satisfies FigmaSelectionHookOptions;

Type declaration

| Name | Type | Description | | :------ | :------ | :------ | | nodeTypes? | readonly SceneNodeType[] | Only return specific types of nodes. If left undefined, all nodes in the selection will be returned. Default: undefined | | resolveProperties? | OptSceneNodeProperties | Figma node properties are lazy-loaded, so to use any property you have to resolve it first. Resolving all node properties causes a performance hit, so you can specify which properties you want to resolve. If set to [], no properties will be resolved and you will only get the ids of the nodes. Node methods (such as getPluginData) will never be resolved. Default: 'all' | | resolveVariables? | OptSceneNodeVariables | Resolve bound variables of the selection. Similarly to resolveProperties, you can specify which variables you want to resolve to optimize performance. If set to [], no properties will be resolved and you will only get the ids of the nodes. Default: [] | | resolveChildren? | boolean | Resolve children nodes of the selection. If nodeTypes is set, all nodes of the specified types will be returned as a flat array. Default: false | | addAncestorsVisibleProperty? | boolean | Add ancestorsVisible property to all nodes. This property is true if all ancestors of the node are visible. Default: false | | pluginDataKeys? | string[] | Get the corresponding plugin data for all nodes. Default: [] | | sharedPluginDataKeys? | OptSharedPluginDataKeys | Get the corresponding shared plugin data for all nodes. The object keys are treated as namespaces and the array values as keys. Default: {} | | apiOptions? | RPCOptions | Options for figma-plugin-api Default: see the RPCOptions type |

FigmaSelectionHookNode

Ƭ FigmaSelectionHookNode<Options>: SerializedResolvedNode<CombineObjects<typeof DEFAULT_HOOK_OPTIONS, Options>>

Utility type to get the inferred type of a node from the hook using the options object

Type parameters

| Name | Type | | :------ | :------ | | Options | extends FigmaSelectionHookOptions = Record<string, never> |

FigmaSelectionHookType

Ƭ FigmaSelectionHookType<Options>: [readonly FigmaSelectionHookNode<Options>[], (selection: readonly BareNode[]) => void, boolean]

Utility type to get the inferred return type of the hook using the options object

[0] - Selected resolved nodes

[1] - A function to set the selection

[2] - Loading state

Type parameters

| Name | Type | | :------ | :------ | | Options | extends FigmaSelectionHookOptions = Record<string, never> |

Variables

FIGMA_MIXED

• Const FIGMA_MIXED: "mixed-57999e63-7384-42a1-acf8-d80b9f6c36a7"

Used to replace figma.mixed during JSON serialization