Composing with Components
Iconify for Vue is one of such components. Yet another icon component? What are advantages over other icon components?
One syntax for over 100,000 icons from 100+ icon sets. Many components simply render icon fonts, which look ugly.
Iconify renders 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. This documentation is for Vue component for Vue 2.
vm.$set( target, propertyName/index, value )
If you are using Vue 3, see documentation for Vue 3 component. If you are using NPM:. If you are using Yarn:. Install @iconify/vue2 and import component from it (component is exported as named export):.
Then in template use Icon component with icon name as icon parameter:. Retrieving icon data from Iconify API requires visitor to be online.
What if you want to use component offline or on local network? There are several options:. You can build icon bundles for icons that are used in your application, making icon data available offline. You can use individual icon packages, which is similar to icon bundles, but import icons one by one and are easier to use.
- See icon bundles for Iconify for Vue 2 documentation.
Component is compatible with Nuxt.js. Component does not retrieve icon data until it is mounted. For server side rendering it means HTML will not include SVGs, they will be dynamically added only when hydrating DOM on client side.
If you do want to render SVGs on server side, use either offline bundle or provide icon data as parameter instead of icon name.
If you want to use icon component's functions that load icon data from API in Nuxt.js, you need Fetch API.
vm.$nextTick( [callback] )
Currently Node.js does not natively support Fetch API. It is available in Node.js version 17 using flag "--experimental-fetch", but without it Fetch API is not available. That means icon component cannot retrieve icon data from Iconify API when used on a server side in Node.js environment.
- How to support API in server side rendering? Install cross-fetch (if you are using CommonJS) or node-fetch (if you are using modules) as dependency.
- Use internal setFetch() function to set third party Fetch API before using any icon component functions. This code must be added only to script that runs on server side, not bundled for client side use.
- Browsers already support Fetch API, so this code is not needed in browsers. You can pass any custom properties to component. Required properties:. icon, IconifyIcon | string icon name or icon data.
- 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.
vm.$delete( target, propertyName/index )
vm.$emit( eventName, […args] )
- 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.
onLoad, function is a callback that is called when icon data has been loaded. 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 name is a string, which has 3 parts:.
provider points to API source. Starts with "@", can be empty (empty value is used for public Iconify API). prefix is name of icon set. name is name of icon. Examples of valid icon names:. flat-color-icons:voice-presentation - icon is "voice-presentation" from Flat Color Icons icon set, from public Iconify API.
- mdi-light:home - icon is "home" from Material Design Light icon set, from public Iconify API.
- If 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 dash.
- This is to support people migrating from icon fonts. For example, fa:arrow-left and fa-arrow-left are identical because "fa" does not contain dash. There are over 100,000 icons available from 100+ icon sets.
- Browse icons sets to see all available icons. You can also add custom API providers for more icon choices. See API providers documentation. 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.
- For various ways to set color, see how to change icon color in Iconify for Vue. 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 (or fontSize if you are using inline 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.
For various ways to change icon dimensions and alignment, see how to change icon dimensions in Iconify for Vue. 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.
- onLoad property is an optional callback function. It is called when icon data has been loaded.
- It is not an event, such as click event for links, it is a simple callback function.
When onLoad is called:. If value of icon property is an object, onLoad is not called. If value of icon property is a string and icon data is available, onLoad is called on first render.
If value of icon 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 of onLoad? To let you know when Icon component renders an icon and when it does not render anything.
- This allows you to do things like adding class name for parent element, such as "container--with-icon" that modify layout if icon is being displayed. 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):.
- There are several functions in this section:. iconExists(name). Checks if an icon exists, returns boolean.
Lists available icons, returns string. Returns icon data, returns IconifyIcon object. Functions for adding icons to component:. addCollection().
Adds an icon set. Note: icons added to component with these functions are not stored in cache.
- Component caches only icons retrieved from API.
- replaceIDs(html). Randomizes IDs in generated string.
This should be used when rendering icon based on data returned by getIcon() to make sure elements inside each icon have unique IDs. calculateSize(). Calculates icon size. It is used to calculate width if only height is set and vice versa. buildIcon(icon, customisations?).
Generates data used by icon component. This can be used if you prefer to generate
Data includes attributes for
addAPIProvider(). Adds custom API provider. See API providers documentation. There are several internal API functions that are exposed. They are intended to be used by developers that need more control over component. For example, it is used in Iconify Icon Finder. Use them carefully. All internal API functions are exposed as properties of _api object:.
Returns internal API module. getAPIConfig(). Returns API configuration. setAPIModule(provider). Sets API module for provider. This is experimental function intended for custom API providers that use custom module for retrieving data from API.
setFetch(fetch). Set custom Fetch API. Returns used fetch() function, null if Fetch API is not available. You’re browsing the documentation for v2.x and earlier. For v3.x, click here. Every Vue application starts by creating a new Vue instance with the Vue function:.
Although not strictly associated with the MVVM pattern, Vue’s design was partly inspired by it.
As a convention, we often use the variable vm (short for ViewModel) to refer to our Vue instance. When you create a Vue instance, you pass in an options object. The majority of this guide describes how you can use these options to create your desired behavior. For reference, you can also browse the full list of options in the API reference.
A Vue application consists of a root Vue instance created with new Vue, optionally organized into a tree of nested, reusable components. For example, a todo app’s component tree might look like this:. We’ll talk about the component system in detail later.
- For now, just know that all Vue components are also Vue instances, and so accept the same options object (except for a few root-specific options).
- When a Vue instance is created, it adds all the properties found in its data object to Vue’s reactivity system.
- When the values of those properties change, the view will “react”, updating to match the new values. When this data changes, the view will re-render.
- It should be noted that properties in data are only reactive if they existed when the instance was created. That means if you add a new property, like:. Then changes to b will not trigger any view updates.
- If you know you’ll need a property later, but it starts out empty or non-existent, you’ll need to set some initial value. The only exception to this being the use of Object.freeze(), which prevents existing properties from being changed, which also means the reactivity system can’t track changes.
- In addition to data properties, Vue instances expose a number of useful instance properties and methods. These are prefixed with $ to differentiate them from user-defined properties.
In the future, you can consult the API reference for a full list of instance properties and methods. Each Vue instance goes through a series of initialization steps when it’s created - for example, it needs to set up data observation, compile the template, mount the instance to the DOM, and update the DOM when data changes.
- Along the way, it also runs functions called lifecycle hooks, giving users the opportunity to add their own code at specific stages.
- For example, the created hook can be used to run code after an instance is created:.
- There are also other hooks which will be called at different stages of the instance’s lifecycle, such as mounted, updated, and destroyed.
All lifecycle hooks are called with their this context pointing to the Vue instance invoking it. Don’t use arrow functions on an options property or callback, such as created: () => console.log(this.a) or vm.$watch('a', newValue => this.myMethod()).