Iconify

https://iconify.design/docs/
Admin
Iconify is a comprehensive icon management system providing over 275k icons from 200+ open source...
Tokens:202,435
Snippets:1,157
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Import IconSet and utilities in example.ts

Source: https://iconify.design/docs/libraries/tools/icon-set/list.html

Imports IconSet and helper functions from @iconify/tools. This is the setup for the example that follows on the page.

```ts
import { IconSet, cleanupSVG, parseColors, isEmptyColor } from '@iconify/tools';
```

--------------------------------

### Install dependencies and build API

Source: https://iconify.design/docs/api/hosting-js/build.html

Run in the repository root to install all dependencies and build the API. Requires Node.js 24 or newer.

```bash
npm install  
 npm run build
```

--------------------------------

### Start API for testing

Source: https://iconify.design/docs/api/hosting-js/build.html

Starts the API. Wait until the terminal shows "API startup process complete" before stopping it with Ctrl+C.

```bash
npm run start
```

--------------------------------

### Configuration examples with from-json and from-folder

Source: https://iconify.design/docs/usage/css/tailwind/tailwind4/custom-icons.html

Two configuration examples: one loading from JSON and folder, another with a custom prefix and square icon option.

```css
@plugin "@iconify/tailwind4" {  
  icon-sets: from-json(test, "./icon-sets/test.json"), from-folder(test2, "./assets/svg");  
 }  
  
@plugin "@iconify/tailwind4" {  
  prefix: "square-icon";  
  square: true;  
  icon-sets: from-folder(test3, "./assets/svg");  
 }
```

--------------------------------

### Keyword query example for /keywords

Source: https://iconify.design/docs/api/keywords.html

Example of a /keywords query using the keyword parameter. The response includes the keyword, pretty flag, exists flag (true), and a list of matches that start or end with the keyword. The query URL is shown after the response.

```json
{
    "keyword": "home",
    "pretty": "1",
    "exists": true,
    "matches": [
        "home2",
        "home3",
        "homee",
        "homewav",
        "homebrew",
        "homestay",
        "homebridge",
        "homeadvisor",
        "homeassistant",
        "homeassistantcommunitystore",
        "esphome",
        "ourhome",
        "eufyhome",
        "googlehome",
        "petsathome",
        "vectorifydahome"
    ]
}
```

```text
/keywords?keyword=home&pretty=1
```

--------------------------------

### TypeScript example using toString()

Source: https://iconify.design/docs/libraries/tools/icon-set/to-string.html

Example that creates an icon set, adds an icon, and exports it as a string using toString().

```ts
import { blankIconSet } from '@iconify/tools';  
  
const iconSet = blankIconSet('');  
 iconSet.setIcon('add', {  
    body: '<g fill="currentColor"><path d="M14 7v1H8v6H7V8H1V7h6V1h1v6h6z"/></g>',  
 });  
  
// Export icon  
console.log(iconSet.toString('add'));
```

--------------------------------

### Install astro-icon

Source: https://iconify.design/docs/usage/svg/astro

Install the astro-icon package as a dev dependency.

```bash
npm i -D astro-icon
```

--------------------------------

### Install icon set package

Source: https://iconify.design/docs/usage/svg-css/react

Install the package for the desired icon set. Replace 'material-symbols' with the icon set name.

```bash
npm install @iconify-react/material-symbols
```

--------------------------------

### Install astro-iconset

Source: https://iconify.design/docs/usage/svg/astro

Install the astro-iconset package as a dev dependency.

```bash
npm i -D astro-iconset
```

--------------------------------

### Install dependencies for converting SVG to Iconify JSON

Source: https://iconify.design/docs/libraries/tools/examples/import-mdi.html

Install the required packages: @iconify/tools and @mdi/svg. This is the first step before running the conversion script.

```bash
npm install @iconify/tools @mdi/svg --save
```

--------------------------------

### Prefix query example for /keywords

Source: https://iconify.design/docs/api/keywords.html

Example of a /keywords query using the prefix parameter. The response includes the prefix, pretty flag, exists flag (false), and a list of matching keywords. The query URL is shown after the response.

```json
{
    "prefix": "hom",
    "pretty": "1",
    "exists": false,
    "matches": [
        "home",
        "home2",
        "home3",
        "homee",
        "homify",
        "homewav",
        "homebrew",
        "homestay",
        "homebridge",
        "homeadvisor",
        "homeassistant",
        "homeassistantcommunitystore"
    ]
}
```

```text
/keywords?prefix=hom&pretty=1
```

--------------------------------

### GET /keywords?prefix={prefix}

Source: https://iconify.design/docs/api/keywords.html

Returns all keywords that start with the requested keyword prefix. The prefix parameter must be set and must be at least 2 characters long, containing only letters a-z, numbers, and hyphens.

```APIDOC
## GET /keywords?prefix={prefix}

### Description
Returns all keywords that start with the requested keyword prefix. The prefix parameter must be set and must be at least 2 characters long, containing only letters a-z, numbers, and hyphens.

### Method
GET

### Endpoint
/keywords?prefix={prefix}

### Parameters
#### Query Parameters
- **prefix** (string) - Required - Keyword prefix. API returns all keywords that start with requested keyword.

### Request Example
/keywords?prefix=hom&pretty=1

### Response
#### Success Response (200)
- **prefix** (string) - The prefix parameter passed in the query.
- **pretty** (string) - The pretty parameter passed in the query (if provided).
- **exists** (boolean) - Set to true if keyword exists as full keyword (with nothing or "-" before and after it in icon name).
- **matches** (string[]) - List of matches.

#### Response Example
{
  "prefix": "hom",
  "pretty": "1",
  "exists": false,
  "matches": [
    "home",
    "home2",
    "home3",
    "homee",
    "homify",
    "homewav",
    "homebrew",
    "homestay",
    "homebridge",
    "homeadvisor",
    "homeassistant",
    "homeassistantcommunitystore"
  ]
}
```

--------------------------------

### Expected output of rotateFromString() example

Source: https://iconify.design/docs/libraries/utils/rotate-from-string.html

Shows the console output produced by the example above. Each line displays the input string and the returned rotation value (0, 1, 2, or 3).

```text
Testing rotate="1": 1  
 Testing rotate="5": 1  
 Testing rotate="-3": 1  
 Testing rotate="90deg": 1  
 Testing rotate="25%": 1  
 Testing rotate="2": 2  
 Testing rotate="-2": 2  
 Testing rotate="180deg": 2  
 Testing rotate="50%": 2  
 Testing rotate="3": 3  
 Testing rotate="-1": 3  
 Testing rotate="270deg": 3  
 Testing rotate="-90deg": 3  
 Testing rotate="75%": 3  
 Testing rotate="-25%": 3  
 Testing rotate="0": 0  
 Testing rotate="0deg": 0  
 Testing rotate="360deg": 0  
 Testing rotate="0%": 0  
 Testing rotate="100%": 0  
 Testing rotate="100deg": 0  
 Testing rotate="40%": 0  
 Testing rotate="none": 0
```

--------------------------------

### bumpVersion() example

Source: https://iconify.design/docs/libraries/tools/package/bump-version.html

Imports bumpVersion from '@iconify/tools' and logs the result of increasing three example version strings: '1.0.0' becomes '1.0.1', '2.1.3' becomes '2.1.4', and '2.0.0-beta.1' becomes '2.0.0-beta.2'. The function takes a version string and returns the updated version number.

```ts
import { bumpVersion } from '@iconify/tools';  
  
console.log(bumpVersion('1.0.0')); // 1.0.1  
console.log(bumpVersion('2.1.3')); // 2.1.4  
console.log(bumpVersion('2.0.0-beta.1')); // 2.0.0-beta.2
```

--------------------------------

### Usage example with defaultIconProps

Source: https://iconify.design/docs/libraries/utils/default-icon-props.html

Shows how to use defaultIconProps to create a full icon object with partial data. The example spreads defaultIconProps and overrides width, height, and hFlip, then logs the resulting icon.

```typescript
import { defaultIconProps } from '@iconify/utils';  
  
const icon = {  
    ...defaultIconProps,  
    body: '<path d="M7 6v12l10-6z" fill="currentColor"/>',  
    width: 24,  
    height: 24,  
    hFlip: true,  
 };  
console.log(icon);
```

```json
{  
    "left": 0,  
    "top": 0,  
    "width": 24,  
    "height": 24,  
    "rotate": 0,  
    "vFlip": false,  
    "hFlip": true,  
    "body": "<path d=\"M7 6v12l10-6z\" fill=\"currentColor\"/>"  
}
```

--------------------------------

### Install dependencies for Iconify Utils

Source: https://iconify.design/docs/usage/css/utils

Installs the required dependencies for generating CSS with Iconify Utils. The @iconify/utils package provides the CSS generation functions, and @iconify/json contains data for all open source icon sets.

```bash
npm install --save-dev @iconify/utils @iconify/json
```

--------------------------------

### Icon set response with categories, hidden, aliases, and suffixes

Source: https://iconify.design/docs/api/collection.html

Icon set response with categories, hidden icons, aliases, and theme suffixes. Categories can be combined with uncategorized from the simple example, so check both properties to get all icons. The actual API response is larger; this example is reduced.

```json
{
    "prefix": "line-md",
    "total": 395,
    "title": "Material Line Icons",
    "categories": {
        "Account": [
            "account",
            "account-add",
            "account-alert",
            "account-delete",
            "account-remove",
            "account-small"
        ],
        "Alerts": [
            "alert",
            "alert-circle",
            "alert-circle-twotone",
            "alert-twotone",
            "bell",
            "bell-twotone",
            "question",
            "question-circle",
            "question-circle-twotone"
        ],
        "Food and Drink": [
            "beer",
            "beer-alt-filled",
            "beer-alt-filled-loop",
            "beer-alt-twotone",
            "beer-alt-twotone-loop",
            "beer-filled",
            "beer-loop",
            "beer-twotone",
            "beer-twotone-loop",
            "coffee",
            "coffee-arrow",
            "coffee-arrow-filled",
            "coffee-arrow-twotone",
            "coffee-filled",
            "coffee-half-empty-twotone-loop",
            "coffee-loop",
            "coffee-twotone",
            "coffee-twotone-loop"
        ]
    },
    "hidden": ["iconify2"],
    "aliases": {
        "beer-alt-solid": "beer-alt-filled",
        "beer-alt-solid-loop": "beer-alt-filled-loop",
        "beer-solid": "beer-filled",
        "check-list-3-solid": "check-list-3-filled",
        "grid-3-solid": "grid-3-filled",
        "list-3-solid": "list-3-filled"
    },
    "suffixes": {
        "": "Outline Animation",
        "out": "Erase Animation",
        "loop": "Looping Animation",
        "transition": "Transition Between Icons"
    }
}
```

--------------------------------

### GET /keywords?keyword={keyword}

Source: https://iconify.design/docs/api/keywords.html

Returns all keywords that start or end with the requested keyword. The keyword parameter must be set and must be at least 2 characters long, containing only letters a-z, numbers, and hyphens.

```APIDOC
## GET /keywords?keyword={keyword}

### Description
Returns all keywords that start or end with the requested keyword. The keyword parameter must be set and must be at least 2 characters long, containing only letters a-z, numbers, and hyphens.

### Method
GET

### Endpoint
/keywords?keyword={keyword}

### Parameters
#### Query Parameters
- **keyword** (string) - Required - Partial keyword. API returns all keywords that start or end with requested keyword.

### Request Example
/keywords?keyword=home&pretty=1

### Response
#### Success Response (200)
- **keyword** (string) - The keyword parameter passed in the query.
- **pretty** (string) - The pretty parameter passed in the query (if provided).
- **exists** (boolean) - Set to true if keyword exists as full keyword (with nothing or "-" before and after it in icon name).
- **matches** (string[]) - List of matches.

#### Response Example
{
  "keyword": "home",
  "pretty": "1",
  "exists": true,
  "matches": [
    "home2",
    "home3",
    "homee",
    "homewav",
    "homebrew",
    "homestay",
    "homebridge",
    "homeadvisor",
    "homeassistant",
    "homeassistantcommunitystore",
    "esphome",
    "ourhome",
    "eufyhome",
    "googlehome",
    "petsathome",
    "vectorifydahome"
  ]
}
```

--------------------------------

### Convert parsed SVG to IconifyIcon with convertParsedSVG()

Source: https://iconify.design/docs/libraries/utils/convert-parsed-svg.html

Example using parseSVGContent() with convertParsedSVG() to get icon data in IconifyIcon format, which can be used by various icon components. The function also does basic validation and cleanup of <svg> attributes. Returns data with type IconifyIcon, undefined on error.

```ts
import { convertParsedSVG, parseSVGContent } from '@iconify/utils';  

// Source SVG with many attributes on <svg> element  
const svg = `<svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-3d-rotate" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">  
  <path d="M12 3a7 7 0 0 1 7 7v4l-3 -3" />  
  <path d="M22 11l-3 3" />  
  <path d="M8 15.5l-5 -3l5 -3l5 3v5.5l-5 3z" />  
  <path d="M3 12.5v5.5l5 3" />  
  <path d="M8 15.545l5 -3.03" />  
 </svg>`  

// Split SVG in <svg> attributes and body  
const parsed = parseSVGContent(svg);  
if (!parsed) {  
    throw new Error('Invalid icon')  
 }  

// Validate and clean up attributes, return IconifyIcon object  
const icon = convertParsedSVG(parsed);  
if (!icon) {  
    throw new Error('Invalid icon')  
 }  

console.log(icon);  

/*  

 {  
  left: 0,  
  top: 0,  
  width: 24,  
  height: 24,  
  body: '<g stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3a7 7 0 0 1 7 7v4l-3 -3" />\n' +  
    '  <path d="M22 11l-3 3" />\n' +  
    '  <path d="M8 15.5l-5 -3l5 -3l5 3v5.5l-5 3z" />\n' +  
    '  <path d="M3 12.5v5.5l5 3" />\n' +  
    '  <path d="M8 15.545l5 -3.03" /></g>'  
 }  

 */
```

--------------------------------

### Default theme example

Source: https://iconify.design/docs/types/iconify-json-metadata.html

Shows how to define a default theme using an empty string key. Icons that do not match other themes belong to the default theme.

```json
{
    "suffixes": {
        "": "Filled",
        "outline": "Outline",
        "negative": "Negative"
    }
}
```

--------------------------------

### React example: Import and render Home icon

Source: https://iconify.design/docs/usage/svg/unplugin

Import the Home icon from the mdi set and render it as a component. The import path uses the '~icons/' prefix.

```tsx
import HomeIcon from '~icons/mdi/home';

function Demo() {
    return (
        <p>
            Home icon: <HomeIcon />
        </p>
    );
}
```

--------------------------------

### Prefixes example (Google Material Icons)

Source: https://iconify.design/docs/types/iconify-json-metadata.html

Shows the prefixes object structure: keys are prefixes, values are theme names. Icons with a matching prefix (plus '-') belong to that theme.

```json
{
    "prefixes": {
        "baseline": "Baseline",
        "outline": "Outline",
        "round": "Round",
        "sharp": "Sharp",
        "twotone": "Two-Tone"
    }
}
```

--------------------------------

### Vue example: Import and render Home icon

Source: https://iconify.design/docs/usage/svg/unplugin

Vue template using the virtual:icons/mdi/home import to render the Home icon.

```vue
<script setup lang="ts">
import MdiHome from 'virtual:icons/mdi/home';
</script>

<template>
    <p>Home icon: <MdiHome /></p>
</template>
```

--------------------------------

### IconifyJSON example

Source: https://iconify.design/docs/types/iconify-json.html

Example of an IconifyJSON object with required properties: prefix and icons. The icon data includes body (SVG path) and optional width/height.

```json
{
    "prefix": "mdi",
    "icons": {
        "home": {
            "body": "<path d=\"M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z\" fill=\"currentColor\"/>",
            "width": 24,
            "height": 24
        }
    }
}
```

--------------------------------

### CSS mask-image with animated SVG data URI

Source: https://iconify.design/docs/api/css.html

Use this CSS snippet to apply an animated SVG icon as a mask image. The SVG data URI includes animated paths with stroke-dasharray and stroke-dashoffset animations. The example is from the 'More examples' section and references the getIconsCSS() function of Iconify Utils for further examples.

```css
mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' width='24' height='24'%3E%3Cg fill='none' stroke='black' stroke-linecap='round' stroke-width='2'%3E%3Cpath stroke-dasharray='20' stroke-dashoffset='20' d='M3 21V20C3 17.7909 4.79086 16 7 16H11C13.2091 16 15 17.7909 15 20V21'%3E%3Canimate fill='freeze' attributeName='stroke-dashoffset' dur='0.4s' values='20;0'/%3E%3C/path%3E%3Cpath stroke-dasharray='20' stroke-dashoffset='20' d='M9 13C7.34315 13 6 11.6569 6 10C6 8.34315 7.34315 7 9 7C10.6569 7 12 8.34315 12 10C12 11.6569 10.6569 13 9 13Z'%3E%3Canimate fill='freeze' attributeName='stroke-dashoffset' begin='0.5s' dur='0.4s' values='20;0'/%3E%3C/path%3E%3Cpath stroke-dasharray='10' stroke-dashoffset='10' d='M15 3L21 9'%3E%3Canimate fill='freeze' attributeName='stroke-dashoffset' begin='1s' dur='0.2s' values='10;0'/%3E%3C/path%3E%3Cpath stroke-dasharray='10' stroke-dashoffset='10' d='M21 3L15 9'%3E%3Canimate fill='freeze' attributeName='stroke-dashoffset' begin='1.2s' dur='0.2s' values='10;0'/%3E%3C/path%3E%3C/g%3E%3C/svg%3E");
```

--------------------------------

### Install @iconify/svelte@4 for Svelte 4

Source: https://iconify.design/docs/articles/migration/icon-v3.html

For Svelte 4 or older, install version 4 of the Svelte component because the new version requires Svelte 5 runes.

```bash
npm install --save-dev @iconify/svelte@4
```

--------------------------------

### Import icon data with default import

Source: https://iconify.design/docs/icons/icons.html

Shows how to import icon data from a split package using a default import, e.g., importing the home icon from @iconify-icons/mdi.

```js
import mdiHome from '@iconify-icons/mdi/home';
```

--------------------------------

### Basic response of /version query

Source: https://iconify.design/docs/api/version.html

Example response from the /version query when STATUS_REGION is not set. Returns plain text with the version number.

```text
Iconify API version 3.0.0-beta.1
```

--------------------------------

### sendAPIQuery() usage example

Source: https://iconify.design/docs/libraries/tools/package/api-query.html

Full example of sending an API query with caching options (3 days TTL) and handling the response. The result is parsed as JSON if it is a string.

```typescript
import { sendAPIQuery } from '@iconify/tools';  
import type { APICacheOptions } from '@iconify/tools/lib/download/api/types';  
  
// 3 days cache  
const ttl = 60 * 60 * 24 * 3;  
const dir = 'cache/api';  
const options: APICacheOptions = {  
    dir,  
    ttl,  
 };  
  
 (async () => {  
    const data = await sendAPIQuery(  
        {  
            uri: 'https://api.iconify.design/collections',  
        },  
        options  
    );  
    console.log(typeof data === 'string' ? JSON.parse(data) : data);  
 })();
```

--------------------------------

### Example: Creating an IconSet and resolving icons

Source: https://iconify.design/docs/libraries/tools/icon-set/resolve.html

Creates an IconSet with icons and aliases, then calls resolve() for a regular icon, a variation (with hFlip), and an alias. The full parameter (true) returns FullIconifyIcon with dimensions and transform properties.

```ts
import { IconSet } from '@iconify/tools';  
  
const iconSet = new IconSet({  
    prefix: 'codicon',  
    icons: {  
        'add': {  
                body: '<g fill="currentColor"><path d="M14 7v1H8v6H7V8H1V7h6V1h1v6h6z"/></g>',  
        },  
        'debug-pause': {  
                body: '<g fill="currentColor"><path d="M4.5 3H6v10H4.5V3zm7 0v10H10V3h1.5z"/></g>',  
                hidden: true,  
        },  
        'triangle-left': {  
                body: '<g fill="currentColor"><path d="M10.44 2l.56.413v11.194l-.54.393L5 8.373v-.827L10.44 2z"/></g>',  
        },  
    },  
    aliases: {  
        'plus': {  
                parent: 'add',  
        },  
        'triangle-right': {  
                parent: 'triangle-left',  
                hFlip: true,  
        },  
    },  
 });  
  
// Resolve icon (partial and full)  
console.log(iconSet.resolve('debug-pause'));  
console.log(iconSet.resolve('debug-pause', true));  
  
// Resolve variation (partial and full)  
console.log(iconSet.resolve('triangle-right'));  
console.log(iconSet.resolve('triangle-right', true));  
  
// Resolve alias (partial and full)  
console.log(iconSet.resolve('plus'));  
console.log(iconSet.resolve('plus', true));
```

--------------------------------

### GET /collection

Source: https://iconify.design/docs/api/collection.html

API query to get a list of icons in an icon set. Requires the icon set prefix and supports optional parameters for including icon set information and character maps.

```APIDOC
## GET /collection

### Description
Retrieves a list of icons in an icon set. The response includes icon names, categories, aliases, and hidden icons, with optional metadata and character maps.

### Method
GET

### Endpoint
/collection

### Parameters
#### Query Parameters
- **prefix** (string) - Required - Icon set prefix.
- **info** (boolean) - Optional - If enabled, the response will include icon set information.
- **chars** (boolean) - Optional - If enabled, the response will include the character map. The character map exists only in icon sets that were imported from icon fonts.

### Response
#### Success Response (200)
- **prefix** (string) - Icon set prefix.
- **total** (number) - Total number of visible icons.
- **uncategorized** (string[]) - List of icon names that aren't in any category.
- **categories** (Record<string,string[]>) - List of icons sorted by categories. Key is category title, value is a list of icon names that belong to that category.
- **hidden** (string[]) - List of hidden icons. Usually icons are marked as hidden if at some point they were removed from the icon set. To prevent user apps from breaking, icons are never deleted, they are marked as hidden instead, but still can be used in apps.
- **aliases** (Record<string,string>) - List of aliases. Key is alias, value is parent icon name.
- **info** (IconifyInfo) - Icon set information, set if info parameter was enabled.
- **title** (string) - Icon set name, usually a duplicate of info.name.
- **chars** (Record<string,string>) - Map of characters, where key is a character as hexadecimal string, value is an icon name. It exists only for icon sets that were imported from icon fonts. It can be used to allow user to search icon name by character code.
- **themes** (object) - Icon set themes. Property themes is deprecated, so it can be ignored.
- **prefixes** (object) - Icon set themes.
- **suffixes** (object) - Icon set themes.
```
Tokens:
Raw