Skip to main content

Working with Variables

Variables in Figma design store reusable values that can be applied to all kinds of design properties and prototyping actions. They help save time and effort when building designs, managing design systems, and creating complex prototyping flows.

Use your plugin to interact with variables in Figma, including creating and reading variables. The Plugin API provides methods using the figma.variables global object to interact with variables.

caution

Variables are currently in beta and subject to change. Learn more: Variables

This guide contains the following sections:

note

This guide assumes that you’re familiar with the basics of creating Figma plugins. If you’re new to developing plugins, check out the Build your first plugin course — you can copy and paste the code from this guide into the plugin you build.

Get variable collections and variables

Use one of the following methods to let your plugin get variables and variable collections.

getLocalVariableCollections

The figma.variables.getLocalVariableCollections method returns all local variable collections in the current file.

Example usage:

const localCollections = figma.variables.getLocalVariableCollections();

getVariableCollectionById

The figma.variables.getVariableCollectionById method finds a variable collection by ID. If not found or the provided ID is invalid, returns null.

Example usage:

const collection = figma.variables.getVariableCollectionById('VariableCollectionId:257c3beb2/57:13');

getLocalVariables

The figma.variables.getLocalVariables method returns all local variables in the current file, optionally filtering by resolved type.

Example usage:

const localVariables = figma.variables.getLocalVariables('STRING'); // filters local variables by the 'STRING' type

getVariableById

The figma.variables.getVariableById method finds a variable by ID. If not found or the provided ID is invalid, returns null.

Example usage:

const variable = figma.variables.getVariableById(variableId);

Create variable collections and variables

Use one of the following methods to create variables or variable collections.

createVariableCollection

To create a variable collection, use the figma.variables.createVariableCollection method.

Example usage:

const collection = figma.variables.createVariableCollection('Example Collection');

createVariable

To create a variable, use the figma.variables.createVariable method.

Example usage:

const variable = figma.variables.createVariable(
  'ExampleVariableName',
  collection.id,
  'STRING'
);

This example creates a variable with the name ExampleVariableName of the STRING type. The variable is created inside a collection with the ID 57:13.

Helpers

The figma.variables global object also provides some helper methods to make certain operations easier.

createVariableAlias

The figma.variables.createVariableAlias method is a helper function to create a variable alias. Variable aliases are used to bind variables to other variables, or to bind variables to various properties on a node or style.

setBoundVariableForPaint

The figma.variables.setBoundVariableForPaint method is a helper function to bind a variable to a SolidPaint.

setBoundVariableForEffect

The figma.variables.setBoundVariableForEffect method is a helper function to bind a variable to an Effect.

setBoundVariableForLayoutGrid

The figma.variables.setBoundVariableForLayoutGrid method is a helper function to bind a variable to a LayoutGrid.

importVariableByKeyAsync

The figma.variables.importVariableByKeyAsync method loads a variable from the team library.

Samples

This section contains some functional plugin samples that use variables.

Example: Authoring a new variable collection

This example creates a new variable collection with two modes, and a color variable that defines a value for each of those two modes.

authoring.js
const collection = figma.variables.createVariableCollection("new-collection")
collection.renameMode(collection.modes[0].modeId, "light")
const colorVariable = figma.variables.createVariable("color-variable", collection.id, "COLOR")

// rename our new variable and collection because naming is hard!
colorVariable.name = "text-primary"
collection.name = "semantic colors"

const lightModeId = collection.modes[0].modeId
const darkModeId = collection.addMode("dark")

// Sets the color to #000 in light mode and #fff in dark mode
colorVariable.setValueForMode(lightModeId, {r: 0, g: 0, b: 0})
colorVariable.setValueForMode(darkModeId, {r: 1, g: 1, b: 1})

Example: Determining if a node is bound to a variable

Variables consumed by a given node are enumerated in the boundVariables map.

detect-if-bound.js
const rectangle = figma.getNodeById(rectangleId)
// rectangle.width is a number
if (rectangle.boundVariables['width'] !== undefined) {
  // Width fields can only have one bound variable, but fills and strokes might have multiple.
  const widthVariableId = rectangle.boundVariables['width'].id
  const widthVariable = figma.variables.getVariableById(widthVariableId)

  // At this point we know that `widthVariable` is bound to the `width` property of `rectangle`.
  assert(widthVariable.resolveForConsumer(rectangle).value === rectangle.width)
}

Example: Binding a variable to a node or style

Whether binding to a node or style, the procedure is roughly the same.

binding.js
const collection = figma.variables.createVariableCollection("new-collection")
const widthVariable = figma.variables.createVariable("width-variable", collection.id, "FLOAT")
const colorVariable = figma.variables.createVariable("color-variable", collection.id, "COLOR")

const node = figma.getNodeById(...)

// Simple fields can be bound via setBoundVariable
node.setBoundVariable('width', widthVariable.id)
const fillsCopy = clone(node.fills)

// Fills and strokes must be set via their immutable arrays
fillsCopy[0] = figma.variables.setBoundVariableForPaint(fillsCopy[0], 'color', colorVariable)
node.fills = fillsCopy

const style = figma.getStyleById(...)
const paintsCopy = clone(style.paints)
paintsCopy[0] = figma.variables.setBoundVariableForPaint(paintsCopy[0], 'color', colorVariable)
style.paints = paintsCopy

// Effects and LayoutGrids must also be set by their immutable arrays
const radiusVariable = figma.variables.createVariable("radius-variable", collection.id, "FLOAT")
const effectsCopy = clone(node.effects)
effectsCopy[0] = figma.variables.setBoundVariableForEffect(effectsCopy[0], 'radius', radiusVariable)
node.effects = effectsCopy

const countVar = figma.variables.createVariable("count-variable", collection.id, "FLOAT")
const layoutGridsCopy = clone(node.layoutGrids)
layoutGridsCopy[0] = figma.variables.setBoundVariableForLayoutGrid(layoutGridsCopy[0], 'count', countVar)
node.layoutGrids = layoutGridsCopy

Example: Binding a variable to a variant property

This sample binds a string variable to the variant property on a InstanceNode

code.js
const instanceNode = figma.getNodeById(...);
const stringVariable = figma.variables.getVariableById(...);
node.setProperties({
  "variantPropName":
    figma.variables.createVariableAlias(stringVariable)
})

// To clear
node.setProperties({
  "variantPropName": "Default", // or other string value
})

Example: Extracting variables from fill styles

Sample code to convert existing styles into variables is available on our GitHub.

Example: Import and export variables

Sample code to help import design tokens from other products or export variables into JSON format. This can further help with migration to variables or syncing design with development. Note that this sample only handles basic import/export and developers are encouraged to extend and customize this code to suit their specific needs.

Sample code on our GitHub

On this page