Iconify for Vue

In addition to SVG framework, Iconify offers native components for several popular UI frameworks. Iconify for Vue is one of such components.

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

  • One syntax for over 70,000 icons from 80+ icon sets.
  • Renders SVG. Many components simply render icon fonts, which look ugly. Iconify renders pixel perfect SVG.

This documentation is for Vue component for Vue 3.

If you are using Vue 2, see documentation for Vue 2 component.

Installation

If you are using NPM:

npm install --save-dev @iconify/vue@beta

If you are using Yarn:

yarn add --dev @iconify/vue@beta

This package does not include icons. Icons are split into separate packages that available at NPM. See below.

Usage

Iconify for Vue is a basic component. It works offline and does not have any dependencies. Icon data is provided as parameter to component.

Install @iconify/vue@beta and packages for selected icon sets. Import component from @iconify/vue and icon data for icon you want to use:

# Installs component and Material Design Light icons
npm install --save-dev @iconify/vue@beta @iconify-icons/mdi-light

Then use Icon component with icon data as icon parameter:

<template>
   
<!-- icon points to variable returned by "data()" method -->
   <Icon :icon="icons.home" />
</template>

<script>

// Import component
import { Icon } from '@iconify/vue';

// Import icon data.
// You can import icon with any name instead of 'homeIcon'
// because exports are not named
import homeIcon from '@iconify-icons/mdi-light/home';

export default {
   components: {
       // Add Icon to list of used components
       Icon,
   },
   data() {
       return {
           // Returns icons data that can be used in template
           icons: {
               // Assign homeIcon to icons.home
               home: homeIcon,
           },
       };
   },
};
</script>

String syntax

Using icon data in Vue requires creating data() method in your component.

However, there is an easier way: assigning a name to icon and calling icon by name.

As a bonus, with this method the icon needs to be added only once. That means if you have multiple components using home icon, you can add it only in your main component. This makes it easy to swap icons for an entire application.

<template>
   
<!-- icon value is the same as first parameter in addIcon() -->
   <Icon icon="home" />
</template>

<script>

// Import component and addIcon function
import { Icon, addIcon } from '@iconify/vue';

// Import icon data.
// You can import icon with any name instead of 'homeIconData'
// because exports are not named
import homeIconData from '@iconify-icons/mdi-light/home';

// Assign name 'home' to icon
addIcon('home', homeIconData);

export default {
   components: {
       // Add Icon to list of used components
       Icon,
   },
};
</script>

Instead of adding icons one by one using addIcon(), you can import an entire icon set using addCollection():

<template>
   <Icon icon="jam:home" height="24" />
</template>

<script>

import { Icon, addCollection } from '@iconify/vue';

// Import requires bundler that can import JSON files
import jamIcons from '@iconify/json/json/jam.json';

// Function automatically adds prefix from icon set, which in this case is 'jam', followed by ':', so
// icon names added by function should be called with prefix, such as 'jam:home'
addCollection(jamIcons);

// Example without prefix, all icons will have names as is, such as 'home'
// addCollection(jamIcons, false);

export default {
   components: {
       Icon,
   },
};
</script>

Example above imports an entire icon set.

To learn how to create smaller bundles, check out Iconify bundles documentation.

Properties

You can pass any custom properties to component.

Required properties:

Optional properties:

  • inline, boolean toggles inline or block mode.
  • width, string | number icon width.
  • height, string | number icon height.
  • horizontalFlip, boolean flips icon horizontally.
  • verticalFlip, boolean flips icon vertically.
  • flip, string alternative to horizontalFlip and verticalFlip.
  • rotate, number | string rotates icon.
  • color, string changes icon color.
  • horizontalAlign horizontally aligns content inside icon.
  • verticalAlign vertically aligns content inside icon.
  • slice alignment behaviour: "meet" or "slice".
  • align, string aligns content inside icon, alternative to horizontalAlign, verticalAlign and slice.

See below for more information on each optional property.

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

Icon

This is a basic component, it cannot retrieve icon data from Iconify API. That means you need to provide icon data yourself.

All icons available with Iconify components and Iconify SVG framework can be imported from NPM packages.

Each icon set has its own package that you need to install. Package names start with @iconify-icons/, followed by icon set prefix.

Each icon is stored in a separate file, so only icons you import are bundled. To import an icon, combine package name and icon name in import statement.

Examples:

  • mdi:image-edit from Material Design Icons can be imported from @iconify-icons/mdi/image-edit.
  • la:envelope-open from Line Awesome can be imported from @iconify-icons/la/envelope-open.
  • tabler:shield-check from Tabler Icons can be imported from @iconify-icons/tabler/shield-check.

...and so on.

Variable name in import statement is irrelevant because all exports are default exports.

CommonJS icon modules

Icons in icon packages are ES modules.

Sometimes you might need CommonJS module, for example, when importing icon data in Node.js.

There are alternative icon packages that use CommonJS modules: @iconify/icons-*. Icons are identical, the only difference is export method. To swap from ES package to CommonJS package, use "@iconify/icons-" before icon set prefix in package name instead of "@iconify-icons/".

For example, Material Design Icons are available as @iconify-icons/mdi with ES exports, as @iconify/icons-mdi with CommonJS exports.

Inline icon

There are two components in Iconify for Vue: Icon and InlineIcon.

They are identical, except for one thing: InlineIcon adds vertical-align style to <svg>. This makes icon behave like an icon font.

See inline icons tutorial for details.

Color

You can only change 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.

<Icon icon="home" style="color: red" />

For various ways to set color, see how to change icon color in Iconify for Vue.

Dimensions and alignment

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

There are several ways to change icon dimensions:

  • Setting font-size in style.
  • Setting width and/or height property.

Values for width and height can be numbers or strings.

If you set only one dimension, another dimension will be calculated using the icon's width to 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.

<Icon icon="home" style="font-size: 24px;" />

For various ways to change icon dimensions and alignment, see how to change icon dimensions in Iconify for Vue.

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 see how to transform icon in Iconify for Vue.