Types in Iconify Icon Finder Core

This tutorial is part of Iconify Icon Finder Core tutorial.

Iconify Icon Finder Core is written in TypeScript. This has several major advantages:

  • You can easily look up properties for objects, parameters for callbacks.
  • When using a library written in TypeScript, editors such as VSCode will give you hints and autofill properties, making it much easier to use that library.
  • Easier to avoid bugs. While core does have unit tests, TypeScript provides an additional layer of code checking, reducing the chance of bugs.

Icon

Each icon is represented by the Icon type.

It has the following required properties:

  • provider, string. API provider, empty string for icons from Iconify Public API.
  • prefix, string. Icon prefix.
  • name, string. Icon name.

Other properties that represent icon metadata and are used only when displaying the collection:

  • tags, string[]. List of tags. In many icon sets tags (or categories) are used to categorise icons.
  • aliases, string[]. List of aliases. Some icons have several names, for example, "home" and "house".
  • chars, string[]. List of characters. This is used when an icon is imported from icon font or has metadata for exporting an icon set to a font. An icon can have multiple characters, so this attribute is an array. Values are hexadecimal strings, such as "f000".
  • themePrefix, string. Theme prefix.
  • themeSuffix, string. Theme suffix. Prefix and suffix are used in some icon sets to create variations of the same icon, such as "-solid" and "-outline". Value contains the title of prefix/suffix used to display prefix/suffix filter, such as "Outline".

To validate and compare icons, following functions are available:

  • validateIcon(icon: Icon | null): boolean. Returns true if icon is valid, false if invalid.
  • compareIcons(icon1: Icon | null, icon2: Icon : null): boolean. Returns true if both icons are valid and identical. This function does not take into account metadata.

To convert icon from/to string, the following functions are available:

  • iconToString(icon: Icon): string. Return string representation of icon, such as "fa-solid:home".
  • stringToIcon(icon: string): Icon | null. Returns Icon object, null if it fails to convert.

IconsList

Type IconsList is used to set icons for a custom view.

It is an array of icon names. Each array entry can be one of the following types:

  • Icon. Icon name as object.
  • string. Icon name as string, such as mdi:home.

You can mix those types if you want to, function will convert all entries to Icon type.

Example:

const icons: IconsList = [
   'bi:bag',
   'bi:bell-fill',
   {
       provider: '',
       prefix: 'bi',
       name: 'stopwatch',
   },
];

core.router.setCustomIcons('recent', icons);

Route

Route is represented by several types:

  • CollectionsRoute. Collections list route (browsing all icon sets).
  • CollectionRoute. Collection view route (browsing one icon set).
  • SearchRoute. Search results.
  • CustomRoute. Custom icons list.

There are generic types that represent any route:

  • Route. Any route mentioned above.
  • PartialRoute. Route with all parameters being optional.

When rendering UI, Icon Finder Core provides data as PartialRoute, so route parameters include only properties that are different from the default and include parent route only if the parent route exists.

For more information about routes, see routes documentation.

CollectionInfo

This type is used to show information about an icon set.

It extends type IconifyInfo from @iconify/types package.

See IconifyInfo for details.

In addition to properties in IconifyInfo type, Icon Finder adds the following properties:

  • prefix, string. Prefix. Duplicate of property in parent object, but this object is re-used in other places where prefix is not provided, so duplication is needed.
  • index, number. Icon set index. It is used to rotate colors in collections list. Each icon set is assigned unique number and to make sure the same color is used for the same icon set everywhere, color is passed in this property instead of using nth-child() in stylesheet.

RouterEvent

Type RouterEvent is an object contains data needed to update UI. It is used in the render callback.

See render callback documentation for details.