Working with Component Properties

Component properties in Figma Design define the changeable aspects of a component.

Component property definitions live on ComponentNode and ComponentSetNode objects. Component property references to these definitions live in component sublayers.

• BOOLEAN properties control node visibility.
• TEXT properties control a node's text content.
• INSTANCE_SWAP properties control which nested instances can be swapped.
• VARIANT properties only exist on ComponentSetNode and define attributes of variants in a component set, such as state, color, or size.
• SLOT properties are flexible areas within a component that let you freely add content.

Get component property definitions

The read-only componentPropertyDefinitions property lets you inspect existing component property definitions for a component or component set.

Get component property definitions

componentSet.componentPropertyDefinitions
// Output
{
  Size: {
    type: 'VARIANT',
    defaultValue: 'Small',
    variantOptions: ['Small', 'Medium', 'Large'],
  },
  IconVisible#0:0: {
    type: 'BOOLEAN',
    defaultValue: false,
  },
  ButtonText#0:1: {
    type: 'TEXT',
    defaultValue: 'submit',
  },
  IconInstance#0:2: {
    type: 'INSTANCE_SWAP',
    defaultValue: '1:1',
    preferredValues: [
      {type: 'COMPONENT', key: 'ckey1'},
      {type: 'COMPONENT_SET', key: 'sgkey1'}
    ],
  },
  MySlot#0:3: {
    type: 'SLOT',
    description: '',
    slotSettings: {},
    preferredValues: []
  }
}

Add boolean, text, instance swap, and variant properties

Adding component properties involves calling addComponentProperty on a ComponentNode or ComponentSetNode and then attaching the property to a sublayer inside the component using componentPropertyReferences.

Add a boolean property

const propId = component.addComponentProperty(
  "IconVisible", // name
  "BOOLEAN", // type
  false, // default value
)
// returns "IconVisible#4:1"

// Attach the newly-created property to the icon sublayer
// inside the component
iconSublayer.componentPropertyReferences = {
  visible: propId
}

Add a text property

const propId = component.addComponentProperty(
  "ButtonText", // name
  "TEXT", // type
  "Label", // default value
)
// returns "ButtonText#4:2"

// Attach the newly-created property to the text sublayer
// inside the component
textSublayer.componentPropertyReferences = {
  characters: propId
}

Add an instance swap property

const propId = component.addComponentProperty(
  "ButtonIcon", // name
  "INSTANCE_SWAP", // type
  "2:22", // id of the default component
  // Optional: define a curated set of components to choose from
  // when swapping instances
  {
    preferredValues: [
      { type: 'COMPONENT', key: '...'  },
      { type: 'COMPONENT_SET', key: '...' }
    ]
  },
)
// returns "ButtonIcon#4:3"

// Attach the newly-created property to the nested instance
// inside the component that can be swapped
nestedInstance.componentPropertyReferences = {
  mainComponent: propId
}

Unlike with other properties, variants in a component set do not refer to variant properties through componentPropertyReferences.

Instead, variant names control variant property values. A variant name like Size=Small, State=Disabled inside a button component set means that the variant defines what a small, disabled button looks like.

Add a variant property

const variantProp = componentSet.addComponentProperty(
  "Size", // name
  "VARIANT", // type
  "Small", // default value
)
// returns "Size"
// All existing variants will be assigned "Size=Small"

const largeHoverVariant = figma.createComponent()
largeHoverVariant.name = 'Size=Large, State=Hover'
componentSet.appendChild(largeHoverVariant)

// Inspect a variant's variant properties without parsing its name
largeHoverVariant.variantProperties
// Output
{ Size: 'Large', State: 'Hover' }

Add slot properties

Use componentNode.createSlot() to create a slot property and a new slot node in a component all in one call. Alternatively, if there is already a frame inside the component that you want to turn into a slot, you can use addComponentProperty() and componentPropertyReferences.

Add a slot property with createSlot()

const slotNode = component.createSlot()

// Define the default content for the slot if you want
slotNode.appendChild(...)

// To edit the component property definition, you can
// obtain the prop id from the slot node you just created
const propId = slotNode.componentPropertyReferences.slotContentId
component.editComponentProperty(propId, {
  preferredValues: [
    { type: 'COMPONENT', key: '...'  },
    { type: 'COMPONENT_SET', key: '...' }
  ],
  description: 'Slot description', // For slot properties only
  slotSettings: { ... }, // For slot properties only
})

Add a slot property with addComponentProperty()

const propId = component.addComponentProperty(
  "MySlot", // name
  "SLOT", // type
  '', // default value,
  // Optional options
  {
    // Define a curated set of components to choose from
    // when adding slot content
    preferredValues: [
      { type: 'COMPONENT', key: '...'  },
      { type: 'COMPONENT_SET', key: '...' }
    ],
    description: 'Slot description', // For slot properties only
    slotSettings: { ... }, // For slot properties only
  },
)
// returns "MySlot#4:3"

// Attach the newly-created property to a frame inside the
// component to make it a slot
slotNode.componentPropertyReferences = { slotContentId: propId }

See SlotSettings for the available fields in the slotSettings object.

Edit and delete component properties

To edit or delete a component property, you need a property id returned from addComponentProperty, componentPropertyDefinitions, or componentPropertyReferences.

Note that renaming a property changes its property id. Subsequent property edits must use the new id.

Edit and delete a component property

// Rename an instance swap property and its default value
component.editComponentProperty(
  "ButtonIcon#4:3",
  {name: "PrimaryButtonIcon", defaultValue: "1:100"}
)
// returns "PrimaryButtonIcon#5:5"

component.deleteComponentProperty("PrimaryButtonIcon#5:5")

Use component properties in instances

Use componentProperties and setProperties on InstanceNode objects to inspect and configure component properties on instances.

Flip a boolean property in an instance

instance.componentProperties
// Output
{
  Size: { type: 'VARIANT', value: 'Large' },
  IconVisible#0:0: { type: 'BOOLEAN', value: false },
  ButtonText#0:1: { type: 'TEXT', value: 'login' },
}

// Make the icon visible in the instance
instance.setProperties({ 'IconVisible#0:0': true })
instance.componentProperties
// Output
{
  Size: { type: 'VARIANT', value: 'Large' },
  IconVisible#0:0: { type: 'BOOLEAN', value: true },
  ButtonText#0:1: { type: 'TEXT', value: 'login' },
}

setProperties does not work for slot properties. To modify slot content in instances, use the same APIs as you would when modifying frame content, since slot content is freely editable, with some restrictions (some nodes are not allowed in slot nodes).

Modify slot content in an instance

// Get the slot node in the instance
// (assume the slot is the first child as an example)
const slotNode = instanceNode.children[0]

const rect = figma.createRectangle()
slotNode.appendChild(rect)

// Reset the slot back to its default contents
slotNode.resetSlot()

Variables as property values

Variables can be used as component property values in instances and as default values in property definitions.

Use a string variable for an instance's text property

instance.setProperties({
  'ButtonText#0:1': figma.variables.createVariableAlias(stringVariable)
})

instance.componentProperties
// Output
{
  ButtonText#0:1: {
    type: 'TEXT',
    value: 'this is the text',
    boundVariables: {
      value: { type: 'VARIABLE_ALIAS', id: 'VariableID:14:9' }
    },
  },
}

Use variables as default component property values

component.editComponentProperty('ButtonText#0:1', {
  defaultValue: figma.variables.createVariableAlias(stringVariable)
})

component.componentPropertyDefinitions
// Output
{
  ButtonText#0:1: {
    type: 'TEXT',
    defaultValue: 'this is the text',
    boundVariables: {
      defaultValue: { type: 'VARIABLE_ALIAS', id: 'VariableID:14:9' }
    }
  }
}