Iconify for Svelte​

Iconify offers native icon components for several popular UI frameworks.

Iconify for Svelte is one of such components.

Yet another icon component? What are the advantages over other icon components?

• One syntax for over 200,000 icons from 150+ icon sets.
• Renders SVG. Many components simply render icon fonts, which look ugly. Iconify uses only pixel perfect SVG.
• Loads icons on demand. No need to bundle icons, component will automatically load icon data for icons that you use from Iconify API.

Please be aware that this component is not designed for server side rendering. If you are using SSR, consider switching toIconify Icon web component.

Installation​

If you are using NPM:

If you are using Yarn:

Svelte 4​

Starting with version 6.0.0 of component, it uses Svelte 5 syntax, which is not compatible with Svelte 4.

If you are using Svelte 4, you need to use version 5 of component:

or use aweb component.

Usage​

Install@iconify/svelte and import component from it (component is exported as default export):

Then in template useIcon component with icon name asicon parameter:

SvelteKit​

Component is compatible with SvelteKit. Syntax is the same as with Svelte.

The component does not retrieve icon data until it is mounted. For server side rendering it means generated HTML will not include SVGs, icons will be rendered only on the client side after hydration is complete.

If you do want to render SVGs on the server side, provideicon data as a parameter instead of icon name oruse a different icon component.

Properties​

You can pass any custom properties toIcon.

Required properties:

• icon,IconifyIcon|string icon name or icon data.

Optional properties:

• inline,boolean changes vertical alignment.
• width,string|number icon width.
• height,string|number icon height.
• hFlip,boolean flips icon horizontally.
• vFlip,boolean flips icon vertically.
• flip,string alternative tohFlip andvFlip.
• rotate,number|string rotates icon.
• color,string changes icon color.
• onLoad,function is a callback that is called when icon data has been loaded. See below.

See below for more information on each optional property.

In addition to the properties mentioned above, the icon component accepts any other properties. All other properties will be passed to generated SVG element, so you can do stuff like setting the inline style, add title and so on.

Unlike React component, Svelte component does not support events.

Icon​

Icon name is a string, which has 3 parts:

Examples of valid icon names:

• flat-color-icons:voice-presentation - icon is "voice-presentation" fromFlat Color Icons icon set, from public Iconify API.
• mdi-light:home - icon is "home" fromMaterial Design Light icon set, from public Iconify API.

Exceptions:

• If the API provider is empty, it can be skipped (like in examples above).
• If prefix does not contain "-", prefix and icon name can be separated with hyphen. This is to support people migrating from icon fonts. For example,fa:arrow-left andfa-arrow-left are identical because "fa" does not contain hyphen.

There are over 200,000 icons available from 150+ icon sets.Browse icons sets to see all available icons.

You can also add custom API providers for more icon choices. SeeAPI providers documentation.

Color​

You can only change the color of monotone icons. Some icons, such as emoji, have a hardcoded palette that cannot be changed.

To add color to a monotone icon, simply change text color.

For various ways to set color, seehow to change icon color in Iconify for Svelte.

Dimensions​

By default, icon height is set to "1em", icon width is changed dynamically based on the icon's width/height ratio. This makes it easy to change icon size by changingfont-size in the stylesheet, just like icon fonts.

There are several ways to change icon dimensions:

• Settingfont-size in style (orfontSize if you are using inline style).
• Settingwidth and/orheight property.

Values forwidth andheight can be numbers or strings.

If you set only one dimension, another dimension will be calculated using the icon's width/height ratio. For example, if the icon size is 16 x 24, you set the height to 48, the width will be set to 32. Calculations work not only with numbers, but also with string values.

For various ways to change icon dimensions, seehow to change icon dimensions in Iconify for Svelte.

Transformations​

An icon can be rotated and flipped horizontally and/or vertically. All transformations are done relative to the center of the icon.

These are not CSS transformations, transformations are applied inside SVG.

For more details seehow to transform icon in Iconify for Svelte.

onLoad​

onLoad property is an optional callback function. It is called when icon data has been loaded.

It is not an event, such asclick event for links, it is a simple callback function.

WhenonLoad is called:

• If value oficon property is an object,onLoad is not called.
• If value oficon property is a string and icon data is available,onLoad is called on first render.
• If value oficon property is a string and icon data is not available,onLoad is called on first re-render after icon data is retrieved from API.

What is the purpose ofonLoad? To let you know whenIcon component renders an icon and when it does not render anything. This allows you to do things like adding class name for the parent element, such as "container--with-icon" that modify layout if icon is being displayed.

Functions​

Component exports various functions, which developers can use to control icons.

Functions are split in several groups (click function name to see more details and examples):

Check available icons​

There are several functions in this section:

• iconLoaded(name). Checks if icon data is available, returnsboolean.
• listIcons(). Lists available icons, returnsstring[].
• getIcon(name). Returns icon data, returnsIconifyIcon object.

Adding icons​

Functions for adding icons to the component:

• addIcon(). Adds one icon.
• addCollection(). Adds an icon set.

Note: icons added to the component with these functions are not stored in the icon data cache. Component caches only icons retrieved from API.

Custom loaders​

Custom loaders can be used to load icons from custom sources:

• setCustomIconLoader(). Loads one icon.
• setCustomIconsLoader(). Loads icons in bulk.

Loaders are set per icon set prefix. Make sure to configure loader before displaying any icons.

It can also be used to customise icons: in custom loader you can load icon from API usingloadIcon, change its content (such as colors or stroke width) and return modified icon.

Helper functions​

• replaceIDs(html). Randomises IDs in generated string. This should be used when rendering icon based on data returned bygetIcon() to make sure elements inside each icon have unique IDs.
• calculateSize(). Calculates icon size. It is used to calculatewidth if onlyheight is set and vice versa.
• buildIcon(icon, customisations?). Generates data used by icon component. This can be used if you prefer to generate<svg> yourself. Data includes attributes for<svg> and inner HTML.

API functions​

• loadIcons(icons, callback?). Loads icons from API, calls optional callback when either all or part of icons have been loaded.
• loadIcon(icon). Loads one icon from API, returnsPromise.
• addAPIProvider(). Adds custom API provider. SeeAPI providers documentation.

Internal API functions​

There are several internal API functions that are exposed. They are intended to be used by developers that need more control over the component. For example, it is used in Sketch and Figma plug-ins. Use them carefully.

All internal API functions are exposed as properties of_api object:

• getAPI(). Returns internal API module.
• getAPIConfig(). Returns API configuration.
• setAPIModule(provider). Sets API module for provider. This is an experimental function intended for custom API providers that use custom module for retrieving data from API.
• setFetch(fetch). Set custom Fetch API.
• getFetch(). Returns usedfetch() function,null if Fetch API is not available.