Types iconify-alias title: Iconify Alias Type types: IconifyIcon: './iconify-icon.md' IconifyJSON: './iconify-json.md' IconifyAlias type All Iconify libraries share common object structures. They are described as types in [npm]@iconify/types NPM package. For description of types and short explanation of TypeScript see types documentation. This article describes [type]IconifyAlias type. IconifyAlias type {#iconify-alias} Type [type]IconifyAlias represents an alias for icon. It is used in Iconify JSON files. What is an alias? An alias is icon that reuses another icon's properties. [icon]arrow-left could be an alias of [icon]arrow-right with horizontal flip enabled. No need to create new shape when existing shape can be reused with a simple transformation. [icon]battery-empty could be an alias of [icon]battery-0 without any changes. This makes it possible to assign multiple names to the same icon. Structure Type [type]IconifyAlias is similar to [type]IconifyIcon. Properties: [prop]parent, [type]string. Name of parent icon, required. Other properties are from [type]IconifyOptional type, they are shared with [type]IconifyIcon type. include types/iconify-optional Parent icon Parent icon name should not include icon set prefix, and parent icon must be present in the icon set. If you use another alias as a parent, make sure there are no circular dependencies. For example, if [icon]arrow-left is an alias of [icon]arrow-right (with horizontal flip), which in turn is an alias of [icon]arrow-up (with 90 degrees rotation), which in turn is an alias of [icon]arrow-down (with vertical flip), [icon]arrow-down could not be an alias of [icon]arrow-left because that would create a loop. To be safe, use only icons as parent, not other aliases. Merging properties for icon and alias If, when merging properties, an icon alias has a property that parent icon also has, the following rules apply: [prop]hFlip and [prop]vFlip. Result is [js]icon.hFlip !== alias.hFlip. That means if both icon and alias are flipped horizontally, the result will not be flipped (horizontal flip + horizontal flip cancel each other). If only one of the items is flipped horizontally, the result will be flipped (horizontal flip + no flip = horizontal flip). [prop]rotate. The result is a sum of rotations. That means 90 degrees rotation + 180 degrees rotation = 270 degrees rotation. For all other properties alias overrides parent icon's value. Examples of merging icon and alias: src: types/icon-merge1.json title: 'Icon:' extra: - src: types/icon-merge1-alias.json title: 'Alias:' - src: types/icon-merge1-result.json title: 'Merged:' In the example above, [js]hFlip + hFlip = false, [js]!vFlip /* default value */ + vFlip = true, icon alias overwrote other properties. Examples src: types/alias-raw.json title: 'IconifyAlias:' extra: - src: types/alias-json.json title: 'IconifyJSON:' - src: types/alias-merged.json title: 'Merged "arrow-right" icon as IconifyIcon:' src: types/alias2-raw.json title: 'IconifyAlias:' extra: - src: types/alias2-json.json title: 'IconifyJSON:' - src: types/alias2-merged.json title: 'Merged "home" icon as IconifyIcon:' src: types/alias3-raw.json title: 'IconifyAlias:' extra: - src: types/alias3-json.json title: 'IconifyJSON:' - src: types/alias3-merged.json title: 'Merged "house-32" icon as IconifyIcon:' iconify-icon title: Iconify Icon Type types: IconifyAlias: './iconify-alias.md' IconifyJSON: './iconify-json.md' functions: getIconData: '../libraries/utils/get-icon-data.md' defaultIconProps: '../libraries/utils/default-icon-props.md' getIcon: '../libraries/tools/svg/index.md' IconifyIcon type All Iconify libraries share common object structures. They are described as types in [npm]@iconify/types NPM package. For description of types and short explanation of TypeScript see types documentation. This article describes [type]IconifyIcon type that contains data for one icon. Usage Icon data in [type]IconifyIcon type is usually extracted from [type]IconifyJSON icon set. To extract icon data in your code, use [func]getIconData() function from Iconify Utils. Iconify Utils can be used in any environment. To convert SVG to [type]IconifyIcon, you can use [func]getIcon() function of [type]SVG instance from Iconify Tools. Iconify Tools is a Node.js package for importing and parsing icons. Make sure you clean up icon before exporting it. Structure Type [type]IconifyIcon is a simple object. It has two parts: [prop]body, [type]string contains icon content, mandatory. Optional [type]IconifyOptional properties that contain icon dimensions and basic transformations. Example of a basic icon: src: types/icon-basic.json copy: false Body Body contains contents of [tag]svg, without [tag]svg tag. It does not include [tag]svg tag because: Contents can be manipulated, such as rotating or flipping an icon. This is much easier to do when there is no need to parse an entire [tag]svg. It gives components full control over [tag]svg tag, allowing addition/removal of custom attributes. Makes it easy to use in various frameworks (such as React, Vue, Svelte), where [tag]svg element is created using framework's native code and content is set as its property. Optional properties {#iconify-optional} There are several properties that are shared in multiple types. They are described in [type]IconifyOptional type. include types/iconify-optional Example of typical icon data: src: types/icon-basic2.json copy: false In your code you can get default values from [var]defaultIconProps constant from Iconify Utils. iconify-info title: Iconify Info Type IconifyInfo type All Iconify libraries share common object structures. They are described as types in [npm]@iconify/types NPM package. For description of types and short explanation of TypeScript see types documentation. This article describes [type]IconifyAlias type. Structure Type [type]IconifyInfo is used for information about icon set. It has the following mandatory properties: [prop]name, [type]string. Icon set name. [prop]author, [type]object. Author information (see below). [prop]license, [type]object. License information (see below). Then it has many optional properties, most of these properties are intended for displaying icon set data in list of icon sets: [prop]total, [type]number. Number of icons in an icon set (see below). [prop]version, [type]string. Version string. [prop]samples, [type]string[]. Array of icon names to show as samples. [prop]height, [type]number | number[]. Icon grid. If an icon set has mix of icons with different height values, such as half of icons are [num]16 pixels high, half are [num]24 pixels high, value can be an array. [prop]displayHeight, [type]number. Height to use when showing samples. Value should be between [num]16 and [num]24. [prop]category, [type]string. Category in icon sets list. [prop]tags, [type]string[]. List of tags, which can be used to filter icon sets (added in version 2). [prop]palette, [type]boolean. Set to true if all icons use hardcoded colors, set to false if all icons use [attr]currentColor. Author [prop]author property is an object with following properties: [prop]name, [type]string. Author name, mandatory. [prop]url, [type]string. Optional link to icon set website. Usually links to GitHub repository. License [prop]license property is an object with following properties: [prop]title, [type]string. Human readable license, mandatory. [prop]spdx, [type]string. Optional SPDX license identifier. [prop]url, [type]string. Optional link to license file. Examples { "name": "Phosphor", "total": 5206, "version": "1.3.2", "author": { "name": "Phosphor Icons", "url": "https://github.com/phosphor-icons/phosphor-icons" }, "license": { "title": "MIT", "spdx": "MIT" }, "samples": [ "folder-notch-open-duotone", "check-square-offset-thin", "pencil-line-fill" ], "height": 24, "displayHeight": 24, "category": "General", "palette": false } { "name": "Emoji One (Colored)", "total": 1834, "version": "2.3.0", "author": { "name": "Emoji One", "url": "https://github.com/EmojiTwo/emojitwo" }, "license": { "title": "CC BY 4.0", "spdx": "CC-BY-4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }, "samples": [ "anxious-face-with-sweat", "cloud-with-snow", "studio-microphone" ], "height": 32, "displayHeight": 16, "category": "Emoji", "palette": true } iconify-json-metadata title: Iconify JSON Metadata types: IconifyIcon: './iconify-icon.md' IconifyAlias: './iconify-alias.md' IconifyJSON: './iconify-json.md' IconifyInfo: './iconify-info.md' IconifyJSON metadata [type]IconifyJSON can also contain additional data that is used for displaying a list of icons: Last modification time (since version 2). Icon set info. Categories. Each icon can belong to multiple categories. Themes. They are used for variations of the same icon that have different start or end parts. Characters map. This is used for icons imported from icon fonts. Last modification time {#last-modified} Last modification time is used to check if an icon set was updated. Icon components use it to invalidate old cache. Value is a number, which needs to be higher than in a previously released version of an icon set. Information {#iconify-info} Information is stored in [prop]info object. See [type]IconifyInfo documentation. Categories {#iconify-categories} Categories are stored in [prop]categories object. In TypeScript categories are represented by type [type]IconifyCategories that can be imported from [npm]@iconify/types. This is a simple object, where key is category name, value is an array of icon names that belong to that category. Example: { "categories": { "Accessibility": ["accessible-icon"], "Audio & Video": ["youtube"], "Communication": ["bluetooth", "bluetooth-b"], "Currency": ["bitcoin", "btc", "ethereum", "gg", "gg-circle"], "Games": [ "playstation", "steam", "steam-square", "steam-symbol", "twitch", "xbox" ] } } Themes: prefixes and suffixes {#themes} Themes are used to display variations of the same icon that have different prefix or suffix. It is similar to categories, but instead of listing every icon, data contains only prefixes or suffixes. Themes are stored in [prop]prefixes and [prop]suffixes objects. In TypeScript both [prop]prefixes and [prop]suffixes are simple [type]Record objects, where: key is prefix or suffix in icon. value is the name of theme. Example of prefixes used in Google Material Icons: { "prefixes": { "baseline": "Baseline", "outline": "Outline", "round": "Round", "sharp": "Sharp", "twotone": "Two-Tone" } } In an example above, all icons that start with [icon]baseline- belong to [str]Baseline theme and so on. When checking if icon belongs to a prefix, add [str]- to prefix. For example, [str]baseline-home belongs to [str]Baseline theme in example above, [str]baselinehome does not, because [str]- should separate prefix and icon name. Example of suffixes used in Ant Design Icons: { "suffixes": { "filled": "Filled", "outlined": "Outlined", "twotone": "TwoTone" } } In an example above, all icons that end with [str]-filled belong to [str]Filled theme, all icons that end with [str]-outlined belong to [str]Outlined theme and all icons that end with [str]-twotone belong to [str]TwoTone theme. Default theme Both prefixes and suffixes can have default entry, where the key is an empty string. Icons that do not fit other themes should be put in that theme. Example: { "suffixes": { "": "Filled", "outline": "Outline", "negative": "Negative" } } Icons that end with [str]-outline belong to [str]Outline theme, icons that end with [str]-negative belong to [str]Negative theme, all other icons belong to [str]Filled theme. Legacy themes In older versions of metadata, themes were stored in [prop]themes property. This has been deprecated and should be ignored. Characters map {#chars} Map of characters is stored in [prop]chars object. In TypeScript characters are represented by type [type]IconifyChars that can be imported from [npm]@iconify/types. This is a simple object, where key is character code in hexadecimal form, value is name of icon. Example: { "chars": { "e007": "firefox-browser", "e013": "ideal", "e01a": "microblog", "e01e": "pied-piper-square", "e049": "unity", "e052": "dailymotion", "e055": "instagram-square", "e056": "mixer", "e057": "shopify" } } iconify-json title: Iconify JSON Type types: IconifyIcon: './iconify-icon.md' IconifyAlias: './iconify-alias.md' functions: getIconData: '/docs/libraries/utils/get-icon-data.md' parseIconSet: '/docs/libraries/utils/parse-icon-set.md' defaultIconProps: '/docs/libraries/utils/default-icon-props.md' IconifyJSON type All Iconify libraries share common object structures. They are described as types in [npm]@iconify/types NPM package. For description of types and short explanation of TypeScript see types documentation. This article describes [type]IconifyJSON type. Usage Icon set in [type]IconifyJSON is created by Iconify Tools or loaded from pre-parsed JSON file. See Iconify Utils documentation for parsing icon sets and icon sets package documentation. See Iconify Tools documentation for creating custom icon sets. Structure Type [type]IconifyJSON is an object that has the following required properties. Required properties [prop]prefix, [type]string. Prefix for icons in JSON file. All icons in an icon set have the same prefix and icon set cannot include icons from other icon sets. [prop]icons, [type]Record. List of icons. Key is icon name, value is [type]IconifyIcon icon data. Example: { "prefix": "mdi", "icons": { "home": { "body": "", "width": 24, "height": 24 } } } Other properties are optional: aliases, default values for all icons, metadata. Icon Object [prop]icons contains data for icons. Key is icon name. Value is icon data, where [prop]body is required and other properties are optional: include types/iconify-optional In your code you can get default values from [var]defaultIconProps constant from Iconify Utils. Alias One optional property of [type]IconifyJSON type is [prop]alias, which has type [type]Record. Key is alias name, value is [type]IconifyAlias alias data. It represents a list of icon aliases. What are aliases? They are variations of other icons. Aliases are used to reduce duplications. For example, if icons [icon]home and [icon]house are identical, only one of those icons can be present in [prop]icons property, another icon can be listed in [prop]aliases, pointing to original icon: { "prefix": "mdi", "icons": { "house": { "body": "", "width": 24, "height": 24 } }, "aliases": { "home": { "parent": "house" } } } Aliases can also include transformations: horizontal and/or vertical flip, 90/180/270 degrees rotation. This allows icon variations by reusing another icon, such as creating a right arrow by using left arrow with horizontal flip: { "prefix": "bi", "icons": { "arrow-left": { "body": "", "width": 16, "height": 16 } }, "aliases": { "arrow-right": { "parent": "arrow-left", "hFlip": true } } } Alias has the same properties as icons, except for [prop]body. It also has additional required property [prop]parent that points to parent icon. Logic for resolving properties of alias: For icon dimensions, value set in alias overrides value from parent icon. For icon transformations, if value is set in both alias and parent icon, they are merged: horizontal flip + horizontal flip = no horizontal flip, 90 degrees rotation + 180 degrees rotation = 270 degrees rotation. src: types/alias-json.json title: 'Source icon set:' hint: 'Icon set as IconifyJSON' extra: - src: types/alias-merged.json title: 'Extracted alias:' hint: 'Merged "arrow-right" icon as IconifyIcon' Another example: src: types/alias3-json.json title: 'Source icon set:' hint: 'Icon set as IconifyJSON' extra: - src: types/alias3-merged.json title: 'Extracted alias:' hint: 'Merged "house-32" icon as IconifyIcon' Default dimensions If most icons in an icon set have the same dimensions, it does not make sense to list them all for each icon: { "prefix": "mdi", "icons": { "home": { "body": "", "width": 24, "height": 24 }, "account": { "body": "", "width": 24, "height": 24 }, "arrow-left": { "body": "", "width": 24, "height": 24 } } } To reduce that duplication, root of [type]IconifyJSON object might include default values for icon dimensions: { "prefix": "mdi", "icons": { "home": { "body": "" }, "account": { "body": "" }, "arrow-left": { "body": "" } }, "width": 24, "height": 24 } These default values are used only for icons that do not have dimensions: src: types/json-defaults-source.json title: 'With default values:' extra: - src: types/json-defaults-merged.json title: 'Without default values:' hint: 'Both examples are identical, first example has default values, second example does not.' If dimensions in an icon are missing, and default values in the root object are missing, default value for property (see the list of properties above) is used: src: types/json-defaults2-source.json title: 'Icon without dimensions, which default to 16:' extra: - src: types/json-defaults2-merged.json title: 'Icon with dimensions:' hint: 'Both examples are identical, first example has default property values, second example has explicit dimensions.' In all examples above, [prop]width and [prop]height are used to demonstrate dimensions. But there are also [prop]left and [prop]top properties and transformations, which are missing in all examples. This is example above with all properties resolved: { "prefix": "bi", "icons": { "arrow-left": { "body": "", "width": 16, "height": 16, "left": 0, "top": 0, "hFlip": false, "vFlip": false, "rotate": false } } } Metadata [type]IconifyJSON can also contain additional data that is used for displaying list of icons. This is optional data that has no effect on rendering icons, so it was moved to a separate document. See IconifyJSON metadata for details. Functions To parse icon sets, Iconify Utils offers the following functions: [func]parseIconSet() parses an entire icon set, calling custom function for every icon. [func]getIconData() extracts data for an icon in [type]IconifyIcon format. To create convert icons to icon sets, use Iconify Tools. index title: Iconify Types types: IconifyIcon: './iconify-icon.md' IconifyAlias: './iconify-alias.md' IconifyJSON: './iconify-json.md' IconifyInfo: './iconify-info.md' Iconify types All Iconify libraries share common object structures. They are described as types in [npm]@iconify/types NPM package. TypeScript All types are described with TypeScript. If you are not familiar with TypeScript, but are familiar with JavaScript, it should not be hard to understand this documentation because it is mostly just basic types. Few basic TypeScript concepts you need to know to understand documentation: Record Type [type]Record is an object, where key is [type]string, value is [type]number. For PHP developers it is the same as associative array. unknown Type [type]unknown means value can be any type. extends src: types/interface.ts copy: false This means one type extends another type. In the example above, type [type]Foo has all properties of types [type]Bar and [type]Baz. Main types There are two main types that are used in Iconify ecosystem: [type]IconifyIcon is used for data for one icon. [type]IconifyJSON is used for an entire icon set. It stores icon data, icon aliases and various metadata. Additional types These types are used in [type]IconifyJSON type: [type]IconifyAlias is used for icon aliases. [type]IconifyInfo is used for icon set information.