# vue3-icon-picker

> Vue 3 icon picker

Latest version **1.0.1** (published 2026-08-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install vue3-icon-picker
pnpm add vue3-icon-picker
yarn add vue3-icon-picker
bun add vue3-icon-picker
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2026-08-12 |
| First published | 2023-03-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 290.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Author | Noé Gnanih |
| Maintainers | arkn |
| Keywords | vue, vue3, icon, picker, iconify |

## Links

- npm: https://www.npmjs.com/package/vue3-icon-picker
- Repository: https://github.com/noeGnh/icon-picker
- Homepage: https://github.com/noeGnh/icon-picker#readme
- Issues: https://github.com/noeGnh/icon-picker/issues
- npm.io page: https://npm.io/package/vue3-icon-picker

## Dependencies (3)

- [@iconify/vue](https://npm.io/package/@iconify/vue.md) ^5.0.1
- [@vueuse/core](https://npm.io/package/@vueuse/core.md) ^14.4.0
- [vue-virtual-scroller](https://npm.io/package/vue-virtual-scroller.md) 3.0.4

## Alternatives

- [@fortawesome/react-fontawesome](https://npm.io/package/@fortawesome/react-fontawesome.md) — 2.2M weekly downloads
- [roboto-fontface](https://npm.io/package/roboto-fontface.md) — 196.0K weekly downloads
- [@react-native-vector-icons/common](https://npm.io/package/@react-native-vector-icons/common.md) — 150.4K weekly downloads
- [@procore/core-icons](https://npm.io/package/@procore/core-icons.md) — 4.6K weekly downloads
- [@react-md/material-icons](https://npm.io/package/@react-md/material-icons.md) — 1.6K weekly downloads

## Recent versions

- 1.0.1 (latest) — 2026-08-12
- 1.0.0 — 2026-08-08
- 0.3.3 — 2026-02-04
- 0.3.2 — 2026-02-04
- 0.3.1 — 2026-02-03
- 0.3.0 — 2026-02-03
- 0.2.2 — 2026-02-02
- 0.2.1 — 2025-07-13
- 0.2.0 — 2025-07-11
- 0.1.4 — 2024-09-20
- 0.1.3 — 2024-05-17
- 0.1.2 — 2024-05-17
- 0.1.1 — 2023-03-28
- 0.1.0 — 2023-03-14
- 0.0.9 — 2023-03-12
- … 8 more at https://npm.io/package/vue3-icon-picker/versions

## README

# Vue 3 Icon Picker ![npm (scoped)](https://img.shields.io/npm/v/vue3-icon-picker)

Icon picker component

<p align="center">
<img width="600" alt="Demo GIF" src="https://github.com/noeGnh/icon-picker/blob/master/demo.gif"/>
</p>

## Installation

If you are using npm:

```sh
npm i vue3-icon-picker
```

If you are using yarn:

```sh
yarn add vue3-icon-picker
```

## About

This package searches icons live from [Iconify](https://iconify.design) - one API, 150+ icon sets, 200,000+ icons (including Font Awesome, Material Symbols, Tabler, Carbon, Fluent, Ant Design, Ionicons and many more). Browse the full catalog at [icon-sets.iconify.design](https://icon-sets.iconify.design). Icons are loaded on demand from Iconify's public API (or your own self-hosted instance, see `iconLibrary`/`apiBase` below) - nothing is bundled into this package.

Before you type anything, the picker shows a default set of icons instead of an empty state: the collection(s) given in `iconLibrary` if any, otherwise a random pick from a small curated set (Tabler, Carbon, Font Awesome, Fluent, Ionicons, Material Symbols, Ant Design).

While a search or the default set is loading, a small status line briefly shows "Loading…" (it disappears once results settle - no persistent count, to stay minimal). The search box gets a clear (×) button once you've typed something, multi-select shows a clear-all button next to the selected badges, and pressing <kbd>Escape</kbd> while the dropdown is open closes it.

## Demo

View the live demo [`here`](https://noegnh.github.io/icon-picker/)

## Usage

You can add this package globally to your project:

```js
// main.js
import { createApp } from 'vue'

import App from './App.vue'

import Vue3IconPicker from 'vue3-icon-picker'
import 'vue3-icon-picker/dist/style.css'

createApp(App).use(Vue3IconPicker).mount('#app')
```

If needed rename component to use:

```js
createApp(App).use(Vue3IconPicker, { name: 'IconPicker' }).mount('#app') // use in template <IconPicker />
```

Alternatively you can also import the component locally:

```js
<script setup>
 import { Vue3IconPicker } from 'vue3-icon-picker'
 import 'vue3-icon-picker/dist/style.css'
</script>
```

You can then use the component in your template

```html
<template>
 <Vue3IconPicker v-model="icon" placeholder="Select icon" />
</template>
```

## Props

| Name                   | Type                          | Description                                                                                                    | Default            | Required |
| ---------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------- | -------- |
| v-model                | string / string[]              | Selection: an Iconify identifier ("tabler:home") or, in `valueType: 'svg'` mode, raw SVG code                    | null                | Yes      |
| placeholder            | string                          | Input placeholder                                                                                                 | undefined            | No       |
| multiple               | boolean                         | Enable multiple selection when set to true                                                                       | false                | No       |
| multipleLimit          | number                          | Maximum number of selections when multiple selection is enabled                                                  | Infinity             | No       |
| selectedItemsToDisplay | number                          | Number of selected icons to display when multiple selection is enabled                                           | 9                    | No       |
| iconLibrary            | string / string[]               | Restrict search to these [Iconify collection prefixes](https://icon-sets.iconify.design) (e.g. "tabler", "carbon"). Searches every collection when omitted | undefined            | No       |
| selectedIconBgColor    | string                          | Selected icon(s) background color (selection is shown as a ring by default; set this for a filled highlight instead) | 'transparent'        | No       |
| selectedIconColor      | string                          | Selected icon(s) color                                                                                            | '#2b5fe0'            | No       |
| clearable              | boolean                         | Make selected icon clearable when multiple is false                                                               | false                | No       |
| disabled               | boolean                         | Disable component                                                                                                 | false                | No       |
| displaySearch          | boolean                         | Display search input                                                                                              | true                 | No       |
| searchPlaceholder      | string                          | Search input placeholder                                                                                          | 'Search'             | No       |
| valueType              | 'name' / 'svg'                  | Store the Iconify identifier (recommended) or a self-contained, portable SVG string                              | 'name'               | No       |
| includeIcons           | string[]                        | Only keep search results whose identifier is in this list                                                        | []                   | No       |
| excludeIcons           | string[]                        | Drop search results whose identifier is in this list                                                             | []                   | No       |
| emptyText              | string                          | Empty text                                                                                                        | 'Nothing to show'    | No       |
| inputSize              | 'small' / 'medium' / 'large'    | Size of input                                                                                                     | 'medium'             | No       |
| theme                  | 'dark' / 'light'                | Picker theme                                                                                                      | 'light'              | No       |

## Slots

| Name  | Parameters | Description                            |
| ----- | ---------- | -------------------------------------- |
| empty | ()         | Empty slot for the dropdown icons list |

## Events

- change
  - This event is fired when selection change.

## Display icons

You can simply display icons like that:

```html
<script setup>
 const icon = ref(null)
</script>

<template>
 <Vue3IconPicker v-model="icon" placeholder="Select icon" />
 <Icon :data="icon" :size="24" color="#124ebb"></Icon>
</template>
```

`Icon`'s `data` prop accepts either an Iconify identifier or a raw SVG string, and renders accordingly - use the same package's `Icon` component so both modes work without extra logic on your side:

```html
<script setup>
 import { Icon } from 'vue3-icon-picker'
 const icon = ref(null)
</script>

<template>
 <Vue3IconPicker v-model="icon" placeholder="Select icon" />
 <Icon :data="icon" :size="24" color="#124ebb"></Icon>
</template>
```

### Icon Props

| Name  | Type            | Description                                       | Default   | Required |
| ----- | --------------- | --------------------------------------------------- | --------- | -------- |
| data  | string          | Iconify identifier ("tabler:home") or raw SVG code   | undefined | Yes      |
| size  | number / string | Icon size                                          | 24        | No       |
| color | string          | Icon color                                         | undefined | No       |

## Migrating from 0.3.x

- `v-model` values are now Iconify identifiers (e.g. `"tabler:home"`) instead of this package's own encoded names (e.g. `"t_HomeOutline"`). Previously stored values will need remapping.
- `valueType` now defaults to `'name'` instead of `'svg'`.
- `iconLibrary` accepts any [Iconify collection prefix](https://icon-sets.iconify.design) instead of a fixed 8-value list. The closest equivalents: `antd` → `ant-design`, `material` → `material-symbols`, `ionicons4`/`ionicons5` → `ion`; `carbon`, `fa`, `fluent`, `tabler` are unchanged.
- `includeSearch`/`excludeSearch` were removed - search is now a live query against Iconify, so there's no separate "preloaded list" to filter twice.
- The picker now requires network access to `api.iconify.design` (or a self-hosted instance) - it no longer bundles any icon assets.

## Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

## Changelog

Detailed changes for each release are documented in the [release notes](https://github.com/noeGnh/icon-picker/releases).

## License

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/noeGnh/icon-picker/blob/master/LICENSE)

---
_Source: https://npm.io/package/vue3-icon-picker · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._