index

目录
title: Importing icons from Figma
types:
  SVG: '../../svg/index.md'
  IconSet: '../../icon-set/index.md'
  IconifyJSON: '/docs/types/iconify-json.md'
  FigmaImportResult: './types.md#result'
  FigmaIconNode: './types.md#icon-node'
  FigmaImportNodeData: './types.md#import-node-data'
  FigmaParentNodeData: './types.md#parent-node-data'
functions:
  cleanupSVG: '../../icon/cleanup.md'
  parseColors: '../../icon/colors.md'
  runSVGO: '../../icon/svgo.md'

Importing icons from Figma

This function is part of import functions in Iconify Tools.

Function [func]importFromFigma() imports SVG files from a Figma file.

It creates [type]IconSet instance, which can be exported to various formats.

Requirements

To import Figma file, you need to have:

Limitations

Import function has few limitations on Figma document structure:

Icon must be one of the following Figma node types:

Parent layers can only be the following Figma node types:

Icons cannot be:

Icons cannot contain:

Usage

Function has the following parameter:

Function returns:

In case of error, import might throw an exception, which you can catch using [func]try and [func]catch.

Function is asynchronous. That means you need to handle it as [class]Promise instance, usually by adding [js]await before function call.

Options

Options object has many properties, most are not required.

Required options used in all parts of import process are:

Required option used when traversing document:

Required option used when generating icon set:

Other options are split in several groups:

Cache options

These options are for caching data:

If you are expecting to run your script more than once, it is a good idea to cache API responses to avoid retrieving the same data multiple times. Set [prop]cacheDir to a writable directory.

TTL options usually do not need changing from default values. Each SVG has unique link, so if icon changes, it will have new cache file, so TTL for icons can be high.

If you set cache options, also consider setting [prop]ifModifiedSince option to true. This will tell import function to retrieve shallow copy of document from Figma, bypassing cache, then comparing if document in Figma has been updated since last cache. If document has been updated, function will clear cache.

const options = {
	// ... other options here
	cacheDir: 'cache/api',
	ifModifiedSince: true,
};

Options for retrieving Figma document

These options are used when retrieving document:

ifModifiedSince

Option [prop]ifModifiedSince is used when you want to retrieve data only if icon set has been updated.

Value can be one of the following:

If Figma document has not been modified, function will return string [str]not_modified.

If option is not set, function cannot return [str]not_modified.

Options for finding icons in Figma document

Function cannot reliably detect which element is an icon and which is not.

These options tell function where to look for icons:

depth

Option [prop]depth tells function how deep it should scan Figma document. Scanning large documents results in slow parsing, so it is recommended to set this option.

Value is number of layers to reach icons.

For example, if icons are placed directly on page without parent group, depth value is [num]2.

Figma tree depth: 2

If icons are placed using the following tree:

Then depth value is [num]3.

Figma tree depth: 3

pages

Option [prop]pages tells function which pages of Figma document contain icons. Value is list of page titles.

Example:

const options = {
	// ... other options here
	pages: ['Icons'],
};

If you set option [prop]pages, option [prop]filterParentNode is ignored.

filterParentNode

Option [prop]filterParentNode is a callback function that filters potential parent nodes.

If possible, it should be used to filter parent nodes, otherwise parser might unexpectedly find and export nodes that match icon, but are on wrong page, that you forgot about.

It is an alternative to [prop]pages option. This option is ignored if [prop]pages option is set.

Callback has the following parameters:

Callback should return:

Callback can be asynchronous.

Example:

const options = {
	// ... other options here

	// 3 levels: page 'Icons' -> frame 'Regular -> icon
	depth: 3,

	// Import icons only from 'Icons' -> 'Regular'
	filterParentNode: (nodes) => {
		switch (nodes.length) {
			case 1: {
				// Page: 'Icons'
				const node = nodes[0];
				return node.name === 'Icons';
			}

			case 2: {
				// Frame: 'Regular'
				const node = nodes[1];
				return node.name === 'Regular';
			}
		}
		return false;
	},
};

iconNameForNode

Option [prop]iconNameForNode is a callback that checks if node is an icon.

Function should return:

Callback parameters are:

Example of callback:

const options = {
	// ... other options here
	iconNameForNode: (node) => {
		if (
			// Icons are stored after 2 parents: page -> container frame -> icon
			node.parents.length !== 2 ||
			// Icons use frames
			node.type !== 'FRAME' ||
			// Icon should be 32x32
			node.width !== 32 ||
			node.height !== 32
		) {
			return null;
		}

		// Return node name as keyword for icon
		return node.name;
	},
};

Callback can be asynchronous.

Options for generating SVG

These options are identical to export settings when you export SVG from Figma:

Options for importing icons

Function imports icons to [type]IconSet instance. These options are for customising import:

Callback functions are identical, the only difference is one is called before importing icon, another one is used after importing icons.

Callbacks have the following parameters:

Callbacks don't need to return anything.

Callbacks can be asynchronous.

Example

The following example imports simple icon set from Figma, where all icons have color [str]#2e4454, then replaces color with [str]currentColor.

src: libraries/tools/import/figma-quill.ts
title: 'example.ts'
版本号 #3
由 壳壳虫 创建于 2026-10-31 14:26:03 UTC
由 cocobook-sync 更新于 2026-11-05 04:10:19 UTC