Use Figma selection in your plugin UI via React hooks.

Supports TypeScript.

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;

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);

  ...
};

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.

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 }) => {
  ...
};

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

Ƭ RPCOptions: Object

Ƭ OptSceneNodeProperties: readonly SceneNodePropertyKey[] | "all"

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

Ƭ OptSceneNodeVariables: readonly BoundVariableKey[] | "all"

Ƭ OptSharedPluginDataKeys: Record<string, string[]>

Ƭ 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;

Ƭ 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

Ƭ 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

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

Used to replace figma.mixed during JSON serialization