---
title: "@farmfe/plugin-icons"
locale: "en"
version: "current"
canonicalUrl: "https://farmfe.org/docs/plugins/official-plugins/icons"
publicationStatus: "prerelease"
---

<a id="farmfeplugin-icons"></a>
# @farmfe/plugin-icons


A Rust Farm plugin for using Iconify icons as on-demand framework components.


<a id="installation"></a>
## Installation


Install the plugin:


**npm**

```javascript
npm install -D @farmfe/plugin-icons
```


**yarn**

```javascript
yarn add -D @farmfe/plugin-icons
```


**pnpm**

```javascript
pnpm add -D @farmfe/plugin-icons
```



Install icon data, either the full Iconify collection:


```bash
npm install -D @iconify/json
```


or a single icon set:


```bash
npm install -D @iconify-json/mdi
```


<a id="usage"></a>
## Usage


Register the plugin in ` farm.config.ts `:


```ts
import { defineConfig } from "@farmfe/core";
import icons from "@farmfe/plugin-icons";

export default defineConfig({
  plugins: [
    icons({
      compiler: "jsx",
      jsx: "react",
      scale: 1.2,
    }),
  ],
});
```


Import icons with the ` ~icons/{collection}/{icon} ` convention:


```jsx
import IconAccessibility from "~icons/carbon/accessibility";
import IconAccountBox from "~icons/mdi/account-box";

export function App() {
  return <IconAccountBox style={{ fontSize: "2em", color: "red" }} />;
}
```


Vue usage follows the same import convention:


```vue
<script setup>
import IconAccessibility from "~icons/carbon/accessibility";
</script>

<template>
  <icon-accessibility />
</template>
```


<a id="options"></a>
## Options


- ` scale?: number ` — icon scale. Defaults to ` 1.2 `.
- ` autoInstall?: boolean ` — automatically install missing icon dependencies. Defaults to ` false `.
- ` compiler?: "jsx" | "vue" | "solid" | "svelte" ` — component compiler. Defaults to ` "jsx" `.
- ` jsx?: "react" | "preact" ` — JSX runtime for the JSX compiler.
- ` defaultStyle?: Partial<CSSStyleDeclaration> ` — default SVG styles.
- ` defaultClass?: string ` — default SVG class.
- ` customCollections?: Record<string, string> ` — custom local or remote icon collections. Use ` [iconname] ` as the icon-name placeholder.


<a id="custom-icons"></a>
## Custom icons


```ts
icons({
  customCollections: {
    local: "./src/assets/icons",
    remote: "https://example.com/icons/[iconname].svg",
  },
});
```


Then import from the custom collections:


```ts
import LocalIcon from "~icons/local/account";
import RemoteIcon from "~icons/remote/foo";
```


Use ` ?raw ` to import raw SVG output:


```ts
import RawIcon from "~icons/mdi/alarm-off?raw&width=4em&height=4em";
```