Iconify Picker
An autonomous web component for selecting icons from Iconify.
Iconify is an open source icon framework. It brings more than 200 icon sets, over 300,000 icons, into one API. This picker lets you search and select those icons in your own app, with no dependencies.
Features
- Zero DependenciesNo external libraries or frameworks required
- Autonomous Web ComponentWorks with any framework or vanilla HTML
- Modern & LightweightBuilt with modern web standards and minimal footprint
- CustomizableEasy to style with CSS custom properties
Installation
Install Iconify Picker using npm (recommended) or via CDN:
1. NPM Package
Install the package using npm:
npm install iconify-pickerImport it in your JavaScript:
import IconifyPicker from 'iconify-picker';Or use it directly in HTML with a script tag:
<script type="module" src="./node_modules/iconify-picker/lib/iconify-picker.js"></script>2. CDN
Alternatively, you can load the component directly from a CDN:
<script type="module" src="https://cdn.jsdelivr.net/npm/iconify-picker/lib/iconify-picker.js"></script>Demo
Iconify Picker can be used in different modes. Here are some demonstrations:
<button id="open-picker">Open Picker</button>
<iconify-picker id="my-picker" mode="manual"></iconify-picker>
<script>
const picker = document.getElementById('my-picker');
const button = document.getElementById('open-picker');
button.addEventListener('click', () => {
picker.toggle();
});
</script>Event Log
Collection with Hidden Search
Example of a picker with a pre-selected collection and hidden search input and collection dropdown:
<iconify-picker
collection="heroicons"
hide-search
hide-collection
page-size="30">
</iconify-picker>Event Log
Vanilla JavaScript Usage
Use Iconify Picker in vanilla JavaScript:
<iconify-picker
id="my-picker"
collection="mdi"
mode="button"
button-label="Choose Icon"
></iconify-picker>
<script type="module">
import IconifyPicker from 'iconify-picker';
const picker = document.getElementById('my-picker');
picker.addEventListener('icon-selected', (e) => {
console.log('Selected:', e.detail.iconName);
});
</script>React Usage
Use Iconify Picker in your React components:
import { useEffect, useRef } from 'react';
import IconifyPicker from 'iconify-picker';
function MyComponent() {
const pickerRef = useRef(null);
useEffect(() => {
const picker = pickerRef.current;
if (picker) {
picker.addEventListener('icon-selected', (e) => {
console.log('Selected:', e.detail.iconName);
});
}
}, []);
return (
<iconify-picker
ref={pickerRef}
collection="mdi"
mode="button"
button-label="Choose Icon"
/>
);
}Vue Usage
Use Iconify Picker in your Vue components:
<template>
<iconify-picker
ref="pickerRef"
collection="mdi"
mode="button"
button-label="Choose Icon"
@icon-selected="handleIconSelected"
/>
</template>
<script setup>
import { ref, onMounted } from 'vue';
import IconifyPicker from 'iconify-picker';
const pickerRef = ref(null);
const handleIconSelected = (e) => {
console.log('Selected:', e.detail.iconName);
};
onMounted(() => {
// Component is ready
});
</script>Angular Usage
Use Iconify Picker in your Angular components:
import { Component, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
import IconifyPicker from 'iconify-picker';
@Component({
selector: 'app-icon-picker',
template: `
<iconify-picker
#pickerRef
collection="mdi"
mode="button"
button-label="Choose Icon"
(icon-selected)="handleIconSelected($event)"
></iconify-picker>
`
})
export class IconPickerComponent implements AfterViewInit {
@ViewChild('pickerRef', { static: false }) pickerRef!: ElementRef<IconifyPicker>;
ngAfterViewInit() {
// Component is ready
}
handleIconSelected(event: CustomEvent) {
console.log('Selected:', event.detail.iconName);
}
}API Reference
Methods
| Method | Description |
|---|---|
show() | Shows the icon picker dialog. |
hide() | Hides the icon picker dialog. |
toggle() | Toggles the icon picker dialog open/close state. |
reset() | Resets the picker: clears selection and search term, reloads icons. |
focus() | Focuses the picker (search input or toggle button). |
Attributes
| Attribute | Default | Description |
|---|---|---|
collection | "" | Icon collection to display (e.g., "mdi", "fa", "heroicons") |
page-size | "60" | Number of icons per page |
height | "" | Height of the picker container |
theme | "auto" | Theme mode: "auto", "light", or "dark" |
search | "" | Initial search term |
selected | "" | Initially selected icon in "collection:name" format |
mode | "inline" | Picker display mode: "inline", "button", or "manual" |
button-label | "Choose Icon" | Label text for button mode |
filter | "" | Filter icons by name pattern |
hidden | false | Hides the picker when set (for manual mode) |
hide-search | false | Hides the search input when set |
hide-collection | false | Hides the collection dropdown when set |
Events
The component fires events that you can listen for to react to user interactions:
| Event Name | Event Detail | Description |
|---|---|---|
icon-selected | { iconName, collection, name, svg } | Fired when an icon is selected |
change | { iconName, collection, name, svg } | Same as icon-selected, for form compatibility |
Example
picker.addEventListener('icon-selected', (e) => {
console.log('Icon:', e.detail.iconName)
console.log('Collection:', e.detail.collection)
console.log('Name:', e.detail.name)
console.log('SVG:', e.detail.svg)
})
// Also fires 'change' event with same detail
picker.addEventListener('change', (e) => {
console.log('Changed to:', e.detail.iconName)
})Customization
Iconify Picker can be styled using CSS custom properties. You can customize colors, spacing, and other visual aspects to match your application's design.
Theme Integration
The component supports automatic theme detection with the theme="auto" attribute. It will adapt to your site's color scheme by:
darkDetecting the class on the HTML elementthemeObserving theme changes in real-timeReading your site's CSS variables for consistent styling
<iconify-picker
collection="mdi"
theme="auto">
</iconify-picker>
You can also manually set the theme with theme="dark" or theme="light".
CSS Variables
| Variable | Default | Description |
|---|---|---|
--picker-primary | #ee6655 | Primary accent color |
--picker-bg | #f2e0e8 | Background color |
--picker-text | #4a3f5c | Text color |
--picker-border | #d9d2e3 | Border color |
--picker-hover | #e8dada | Hover state background |
--picker-header-bg | #f2e0e8 | Header background color |
--picker-input-bg | #f7f3fa | Input fields background color |
--picker-input-text | #4a3f5c | Input fields text color |
--picker-icon-color | #4a3f5c | Icon color |
--picker-footer-bg | #f2e0e8 | Footer background color |
--picker-radius | 12px | Default border radius (used as fallback) |
--picker-container-radius | 12px | Border radius for main container |
--picker-input-radius | 8px | Border radius for inputs and controls |
--picker-icon-radius | 6px | Border radius for icon items |
--picker-button-radius | 8px | Border radius for buttons |
--picker-border-width | 3px | Default border width (used as fallback) |
--picker-container-border-width | 3px | Border width for main container |
--picker-input-border-width | 1px | Border width for inputs and controls |
--picker-icon-border-width | 1px | Border width for icon items |
--picker-padding | 1rem | Internal padding for elements |
--picker-gap | 0.5rem | Gap between elements |
--picker-icon-size | 24px | Size of the icons in the grid |
--picker-cell-size | 60px | Minimum width of each grid cell (controls columns) |
--picker-max-height | 60vh | Maximum height of the component |
| Scrollbar Customization | ||
--picker-scrollbar-width | thin | Scrollbar width (thin, auto, none) |
--picker-scrollbar-color | #ee6655 | Scrollbar thumb color |
--picker-scrollbar-track | transparent | Scrollbar track background |
--picker-scrollbar-hover | #ee8877 | Scrollbar thumb hover color |
Example CSS
/* Custom CSS for iconify-picker */
iconify-picker {
--picker-primary: #ee6655;
--picker-bg: #f2e0e8;
--picker-text: #4a3f5c;
--picker-border: #d9d2e3;
--picker-hover: #e8dada;
--picker-header-bg: #f2e0e8;
--picker-input-bg: #f7f3fa;
--picker-input-text: #4a3f5c;
--picker-icon-color: #4a3f5c;
--picker-footer-bg: #f2e0e8;
--picker-radius: 12px;
--picker-container-radius: 12px;
--picker-input-radius: 8px;
--picker-icon-radius: 6px;
--picker-button-radius: 8px;
--picker-border-width: 3px;
--picker-container-border-width: 3px;
--picker-input-border-width: 1px;
--picker-icon-border-width: 1px;
--picker-padding: 1rem;
--picker-gap: 0.5rem;
--picker-icon-size: 24px;
--picker-cell-size: 60px;
--picker-max-height: 60vh;
/* Scrollbar customization */
--picker-scrollbar-width: thin;
--picker-scrollbar-color: #ee6655;
--picker-scrollbar-track: transparent;
--picker-scrollbar-hover: #ee8877;
}
/* Dark mode customization */
@media (prefers-color-scheme: dark) {
iconify-picker {
--picker-bg: #1c1a21;
--picker-text: #eae7ef;
--picker-border: #4a3d5c;
--picker-hover: #232028;
--picker-header-bg: #1c1a21;
--picker-input-bg: #232028;
--picker-input-text: #eae7ef;
--picker-icon-color: #eae7ef;
--picker-footer-bg: #1c1a21;
--picker-scrollbar-color: #ee6655;
--picker-scrollbar-hover: #ee8877;
}
}Interactive Customization
Main Colors
Element Colors
Scrollbar
Border Radius
Border Width
Spacing & Dimensions
/* Custom CSS for iconify-picker */
iconify-picker {
--picker-primary: #ee6655;
--picker-bg: #f2e0e8;
--picker-text: #4a3f5c;
--picker-border: #d9d2e3;
--picker-hover: #e8dada;
--picker-header-bg: #f2e0e8;
--picker-input-bg: #f7f3fa;
--picker-input-text: #4a3f5c;
--picker-icon-color: #4a3f5c;
--picker-footer-bg: #f2e0e8;
--picker-radius: 12px;
--picker-container-radius: 12px;
--picker-input-radius: 8px;
--picker-icon-radius: 6px;
--picker-button-radius: 8px;
--picker-border-width: 3px;
--picker-container-border-width: 3px;
--picker-input-border-width: 1px;
--picker-icon-border-width: 1px;
--picker-padding: 1rem;
--picker-gap: 0.5rem;
--picker-icon-size: 24px;
--picker-cell-size: 60px;
--picker-max-height: 60vh;
/* Scrollbar customization */
--picker-scrollbar-width: thin;
--picker-scrollbar-color: #ee6655;
--picker-scrollbar-track: transparent;
--picker-scrollbar-hover: #ee8877;
}
/* Dark mode customization */
@media (prefers-color-scheme: dark) {
iconify-picker {
--picker-bg: #1c1a21;
--picker-text: #eae7ef;
--picker-border: #4a3d5c;
--picker-hover: #232028;
--picker-header-bg: #1c1a21;
--picker-input-bg: #232028;
--picker-input-text: #eae7ef;
--picker-icon-color: #eae7ef;
--picker-footer-bg: #1c1a21;
--picker-scrollbar-color: #ee6655;
--picker-scrollbar-hover: #ee8877;
}
}