Skip to main content

Shader

A shader is a programmable effect or fill you can apply to a node. These types describe the shaders returned by figma.listAvailableShaders and figma.importShaderById, and the property values you read and write when a shader is applied as a ShaderEffect or ShaderPaint.

A shader must be imported into the file before it can be applied. listAvailableShaders returns owned and subscribed-library shaders that aren't loaded in the file yet with imported: false; importing one brings it into the file and populates its propertyDefinitions. After that, apply it by setting a { type: 'SHADER', id } entry on node.effects (for an effect shader), or on node.fills / node.strokes (for a fill shader).

Importing a shader​

const shaders = await figma.listAvailableShaders()
const shader = shaders.find((s) => s.name === 'Fractal Noise')
if (!shader) {
  figma.notify('Shader not found')
  figma.closePlugin()
  return
}

// Import the shader if it isn't in the file yet. After importing, `imported` is
// `true` and `propertyDefinitions` is populated.
const ready = shader.imported ? shader : await figma.importShaderById(shader.id)

Configuring properties​

A shader's properties map is keyed by property-definition id, not by property name. Read propertyDefinitions to find the id for each named property, then build the properties map for the values you want to set. The shape of each value must match the property's declared type (see ShaderPropertyValue).

// Build a `properties` map by looking up each property's id from its name.
const properties: { [defId: string]: ShaderPropertyValue } = {}
for (const [defId, def] of Object.entries(ready.propertyDefinitions ?? {})) {
  if (def.name === 'scale' && def.type === 'NUMBER') {
    properties[defId] = 4
  } else if (def.name === 'tint' && def.type === 'COLOR') {
    properties[defId] = { r: 1, g: 0, b: 0.5 }
  } else if (def.name === 'center' && def.type === 'POINT') {
    properties[defId] = { x: 0.5, y: 0.5 }
  }
}

Applying as an effect​

An effect shader is applied through node.effects as a ShaderEffect. visible is required.

node.effects = [{ type: 'SHADER', id: ready.id, visible: true, properties }]

Applying as a fill or a stroke​

A fill shader is applied through node.fills or node.strokes as a ShaderPaint, alongside any other paints.

node.fills = [{ type: 'SHADER', id: ready.id, properties }]
node.strokes = [{ type: 'SHADER', id: ready.id, properties }]

Reading properties back​

When you read effects, fills, or strokes, each shader entry's properties map is populated with its current assignments — including author-defined defaults — so you can discover the available ids after a shader is applied.

const [fill] = node.fills
if (fill?.type === 'SHADER') {
  for (const [defId, value] of Object.entries(fill.properties ?? {})) {
    console.log(defId, value)
  }
}

Shader​

id: string [readonly]

A stable identifier for the shader. The same value round-trips through figma.importShaderById and the id field of a ShaderEffect / ShaderPaint when applying the shader.

name: string [readonly]

The name of the shader.

type: 'effect' | 'fill' [readonly]

Whether the shader applies as an effect (node.effects) or as a fill (node.fills / node.strokes).

imported: boolean [readonly]

Whether the shader has been imported into the file yet. When false, call figma.importShaderById with this shader's id before applying it.

propertyDefinitions?: { [defId: string]: ShaderPropertyDefinition } [readonly]

The shader's declared properties, keyed by property-definition id. Populated for imported shaders; may be absent until the shader is imported.

ShaderPropertyDefinition​

name: string [readonly]

The author-defined name of the property.

type: 'BOOLEAN' | 'TEXT' | 'NUMBER' | 'IMAGE' | 'INSTANCE_SWAP' | 'SLOT' | 'COLOR' | 'POINT' | 'LINE' | 'CIRCLE' | 'CIRCLE_POINT' | 'COLOR_POINT' | 'GRADIENT' [readonly]

The declared type of the property. This determines which shape of ShaderPropertyValue is valid for it. POINT corresponds to the editor's "point" property type.

defaultValue?: ShaderPropertyValue [readonly]

The author-defined default value for the property, if any.

description?: string [readonly]

The author-defined description of the property, if any.

ShaderPropertyValue​

A single value assignable to a shader property. The shape that's valid for a given property depends on that property's declared type in its ShaderPropertyDefinition. Any value may also be a VariableAlias to bind the property to a variable.

type ShaderPropertyValue =
  | boolean // BOOLEAN
  | string // TEXT
  | number // NUMBER
  | RGB // COLOR
  | RGBA // COLOR
  | { x: number; y: number } // POINT
  | { x: number; y: number; x2: number; y2: number } // LINE
  | { x: number; y: number; radius: number } // CIRCLE
  | { x: number; y: number; radius: number; angle: number } // CIRCLE_POINT
  | { x: number; y: number; color: RGB | RGBA | VariableAlias } // COLOR_POINT
  | { stops: { position: number; color: RGB | RGBA | VariableAlias }[] } // GRADIENT
  | VariableAlias