import areaChartOutlined from '@iconify-icons/ant-design/area-chart-outlined';
export default {
components: {
IconifyIcon,
},
data() {
return {
icons: {
chart: areaChartOutlined,
},
};
},
};
</script>
```
### String syntax
String syntax passes icon name to the component.
With this method the icon needs to be added only once. That means if you have multiple components using 'chart' icon, you can add it only in your main component. This makes it easy to swap icons for an entire application.
```vue
<template>
<iconify-iconicon="chart"height="24"/>
</template>
<scriptlang="ts">
import { Component, Prop, Vue } from 'vue-property-decorator';
import IconifyIcon from '@iconify/vue';
import areaChartOutlined from '@iconify-icons/ant-design/area-chart-outlined';
IconifyIcon.addIcon('chart', areaChartOutlined);
export default Vue.extend({
components: {
IconifyIcon,
},
});
</script>
```
The icon must be registered using `addIcon` function of the component. You can assign any name to the icon.
The same example without TypeScript:
```vue
<template>
<iconify-iconicon="chart"height="24"/>
</template>
<script>
import IconifyIcon from '@iconify/vue';
import areaChartOutlined from '@iconify-icons/ant-design/area-chart-outlined';
Instead of adding icons one by one using `addIcon` function, you can import an entire icon set using `addCollection` function:
```vue
<template>
<iconify-iconicon="jam:home"/>
</template>
<script>
import IconifyIcon 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'
IconifyIcon.addCollection(jamIcons);
export default {
components: {
IconifyIcon,
},
};
</script>
```
Example above imports an entire icon set. To learn how to create smaller bundles, check out Iconify documentation: https://docs.iconify.design/sources/bundles/
You can install the icon component using `Vue.use()`, then you will no longer need to add it to every component that uses icons.
```js
import IconifyIcon from '@iconify/vue';
Vue.use(IconifyIcon);
```
If you are using TypeScript with Vue, it becomes a bit more complex. You need to import type `PluginObject` from Vue and do some shenanigans with type casting:
```ts
import { PluginObject } from 'vue';
import IconifyIcon from '@iconify/vue';
Vue.use((IconifyIcon as unknown) as PluginObject<unknown>);
```
After installing the icon component, you no longer need to list `IconifyIcon` in components list every time you use it.
`icon` property is mandatory. It tells component what icon to render. If the property value is invalid, the component will render an empty icon. The value can be a string containing the icon name (icon must be registered before use by calling `addIcon` or `addCollection`, see instructions above) or an object containing the icon data.
-`rotate`. Rotate icon by 90, 180 or 270 degrees. See "Transformations" section below.
-`align`, `verticalAlign`, `horizontalAlign`, `slice`. Icon alignment. See "Alignment" section below.
Note: in templates you can use "camelCase" properties as "kebab-case". For example, `hFlip` can be used as `h-flip`.
### Other properties and events
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 assigning click event, setting the inline style, create element reference, add title and so on.
### Dimensions
By default, icon height is "1em". With is dynamic, calculated using the icon's width to height ratio.
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.
Be careful when using `calc`, view port based units or percentages. In SVG element they might not behave the way you expect them to behave and when using such units, you should consider settings both width and height.
#### Dimensions as 'auto'
Keyword "auto" sets dimensions to the icon's `viewBox` dimensions. For example, for 24 x 24 icon using `height="auto"` sets height to 24 pixels.
```html
<iconify-iconicon="experiment"height="auto"/>
```
### Icon colour
There are two types of icons: icons that do not have a palette and icons that do have a palette.
Icons that do have a palette, such as emojis, cannot be customised. Setting colour to such icons will not change anything.
Icons that do not have a palette can be customised. By default, colour is set to "currentColor", which means the icon's colour matches text colour. To change the colour you can:
- Set `color` style or use stylesheet to target icon. If you are using the stylesheet, target `svg` element, not `iconify-icon`.
This might seem redundant because icon can also be rotated and flipped using CSS transformations. So why do transformation properties exist? Because it is a different type of transformation.
- CSS transformations transform the entire icon.
- Icon transformations transform the contents of the icon.
If you have a square icon, this makes no difference. However, if you have an icon that has different width and height values, it makes a huge difference.
Rotating 16x24 icon by 90 degrees results in:
- CSS transformation keeps 16x24 bounding box, which might cause the icon to overlap text around it.
- Icon transformation changes bounding box to 24x16, rotating content inside an icon.
_TODO: show visual example_
#### Flipping an icon
There are several properties available to flip an icon:
-`horizontal-flip` or `h-flip`: boolean property, flips icon horizontally.
-`vertical-flip` or `v-flip`: boolean property, flips icon vertically.
-`flip`: shorthand string property, can flip icon horizontally and/or vertically.
Why are there multiple boolean properties for flipping an icon? See "Alignment" section below for the explanation.
#### Rotating an icon
An icon can be rotated by 90, 180 and 270 degrees. Only contents of the icon are rotated.
To rotate an icon, use `rotate` property. Value can be a string (degrees or percentages) or a number.
Number values are 1 for 90 degrees, 2 for 180 degrees, 3 for 270 degrees.
Examples of 90 degrees rotation:
```html
<iconify-iconicon="experiment":rotate="1"/>
<iconify-iconicon="experiment"rotate="90deg"/>
<iconify-iconicon="experiment"rotate="25%"/>
```
### Alignment
Alignment matters only if you set the icon's width and height properties that do not match the viewBox with and height.
For example, if the icon is 24x24 and you set the width to 32 and height to 24. You must set both `width` and `height` properties for this to happen or use stylesheet to set both icon's width and height.
#### Stretching SVG
When you use incorrect width/height ratio for other images, browser stretches those images.
Unlike other images, SVG elements do not stretch. Instead, browser either adds space on sides of the icon (this is the default behaviour) or crops part of the icon.
![Stretching image and SVG](https://iconify.design/assets/images/align-img.svg)
#### Alignment properties
You can control the behaviour of SVG when using incorrect width/height ratio by setting alignment properties:
-`horizontal-align` or `h-align`: string property to set horizontal alignment. Possible values are "left", "center" and "right".
-`vertical-align` or `v-align`: string property to set vertical alignment. Possible values are "top", "middle" and "bottom".
-`slice`: boolean property. See below.
-`align`: shorthand string property. Value is the combination of vertical alignment values, horizontal alignment values, "meet" (same as `:slice="false"`) and "slice" (same as `:slice="true"`) separated by comma.
Why are there aliases for `h-align` and `v-align` properties? Because in Vue properties that start with `v-` are treated as directives. It is possible to use `v-align` property using a weird syntax (see example below), but it is much cleaner to have a different name for that property, so that is why Vue component has aliases for those properties. For more consistent properties, similar aliases were added to `h-flip` and `v-flip` properties.
Example of aligning an icon to the left if icon is not square:
The icon component renders `SVG` elements. By default, `SVG` behave like images, which is different from icon fonts.
Many developers are used to working with icon fonts. Icon fonts render icons as text, not as images. Browsers align text differently than images:
- Images are vertically aligned at baseline.
- Text is vertically aligned slightly below baseline.
By adding `inline` property, icon behaves like text. In inline mode icon has vertical alignment set to "-0.125em". That puts icon just below baseline, similar to icon fonts.
Example:
```html
<iconify-iconicon="experiment":inline="true"/>
```
Value is boolean, therefore ":" must be added before property name, changing the value from string to expression.
Visual example to show the difference between inline and block modes:
There are over 80 icon sets. This readme shows only a few examples. See [Iconify icon sets](http://iconify.design/icon-sets/) for a full list of available icon sets. Click any icon to see code.