List of icons
You can get list of icon in an icon set sets using /collection API query.
Query
API query is /collection.
Required parameter:
- prefix, string. Icon set prefix.
Optional parameters:
- info, boolean. If enabled, response will include icon set information.
- chars, boolean. If enabled, response will include characters map. Characters map exists only in icon sets that were imported from icon fonts.
Response
Response is a complex object with the following required properties:
- prefix, string - icon set prefix.
- total, number - total number of visible icons.
Then there are many optional properties.
Icons
Properties that are relevant for list of 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 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 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.
To get list of all icon names that should be shown, use the following logic:
- Get values from uncategorized property, if it exsts.
- Traverse all categories from categories property, if it exsts. One icon can exist in multiple categories, so check for duplicates, easiest way to do that is to use Set class in JavaScript instead of Array.
To get all icon names, add to result above:
- Keys of aliases object, if it exists. Should not be displayed in icons list because they are duplicate names for other icons.
- Values from hidden property, if it exists. Should not be displayed in icons list because these are hidden icons. To prevent user apps from breaking, icons are never deleted, they are marked as hidden instead, but still can be used in apps.
Other properties
Other optional properties:
- 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> - characters map, where key is character as hexadecimal string, value is 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, prefixes and suffixes - icon set themes. Property themes is deprecated, so it can be ignored.
See IconifyJSON type and metadata documentation.
Only icon sets that have info can be browsed. If you want to hide an icon set, do not set info object when importing it.
Simple example
This is a basic icon set, without categories or any extra metadata:
{
"prefix": "mdi-light",
"total": 267,
"title": "Material Design Light",
"uncategorized": [
"account",
"account-alert",
"alarm",
"alarm-plus",
"alert",
"alert-circle",
"alert-octagon",
"arrange-bring-forward",
"arrange-bring-to-front",
"arrange-send-backward",
"arrange-send-to-back",
"arrow-down",
"arrow-down-circle",
"arrow-left",
"arrow-left-circle",
"arrow-right",
"arrow-right-circle",
"arrow-up",
"arrow-up-circle",
"view-dashboard",
"view-module",
"volume",
"volume-minus",
"volume-mute",
"volume-off",
"volume-plus",
"wallet",
"wifi",
"xml"
]
}
/collection?prefix=mdi-light&pretty=1
Actual API response is a lot bigger. Example was reduced.
Categories example
Icon set in example below:
- uses categories to sort icons (categories can be combined with uncategorized from example above, so check both properties to get all icons).
- has hidden icons.
- has aliases.
- has theme suffixes.
{
"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"
}
}
/collection?prefix=line-md&pretty=1
Actual API response is a lot bigger. Example was reduced.
Error response
If icon set is not found or cannot be browsed, server returns 404 HTTP error.
If browsing icons is disabled, route is not handled, server returns 404 HTTP error.
Type
Type for API response:
import type { IconifyInfo, IconifyJSON } from '@iconify/types';
export interface APIv2CollectionResponse {
// Icon set prefix
prefix: string;
// Number of icons (duplicate of info?.total)
total: number;
// Icon set title, if available (duplicate of info?.name)
title?: string;
// Icon set info
info?: IconifyInfo;
// List of icons without categories
uncategorized?: string[];
// List of icons, sorted by category
categories?: Record<string, string[]>;
// List of hidden icons
hidden?: string[];
// List of aliases, key = alias, value = parent icon
aliases?: Record<string, string>;
// Characters, key = character, value = icon name
chars?: Record<string, string>;
// Themes
themes?: IconifyJSON['themes'];
prefixes?: IconifyJSON['prefixes'];
suffixes?: IconifyJSON['suffixes'];
}