GitHub

Iconify Picker

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

Installation

Install Iconify Picker using npm (recommended) or via CDN:

1. NPM Package

Install the package using npm:

npm install iconify-picker

Import 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

MethodDescription
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

AttributeDefaultDescription
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
hiddenfalseHides the picker when set (for manual mode)
hide-searchfalseHides the search input when set
hide-collectionfalseHides the collection dropdown when set

Events

The component fires events that you can listen for to react to user interactions:

Event NameEvent DetailDescription
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 element
  • themeObserving theme changes in real-time
  • Reading 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

VariableDefaultDescription
--picker-primary#ee6655Primary accent color
--picker-bg#f2e0e8Background color
--picker-text#4a3f5cText color
--picker-border#d9d2e3Border color
--picker-hover#e8dadaHover state background
--picker-header-bg#f2e0e8Header background color
--picker-input-bg#f7f3faInput fields background color
--picker-input-text#4a3f5cInput fields text color
--picker-icon-color#4a3f5cIcon color
--picker-footer-bg#f2e0e8Footer background color
--picker-radius12pxDefault border radius (used as fallback)
--picker-container-radius12pxBorder radius for main container
--picker-input-radius8pxBorder radius for inputs and controls
--picker-icon-radius6pxBorder radius for icon items
--picker-button-radius8pxBorder radius for buttons
--picker-border-width3pxDefault border width (used as fallback)
--picker-container-border-width3pxBorder width for main container
--picker-input-border-width1pxBorder width for inputs and controls
--picker-icon-border-width1pxBorder width for icon items
--picker-padding1remInternal padding for elements
--picker-gap0.5remGap between elements
--picker-icon-size24pxSize of the icons in the grid
--picker-cell-size60pxMinimum width of each grid cell (controls columns)
--picker-max-height60vhMaximum height of the component
Scrollbar Customization
--picker-scrollbar-widththinScrollbar width (thin, auto, none)
--picker-scrollbar-color#ee6655Scrollbar thumb color
--picker-scrollbar-tracktransparentScrollbar track background
--picker-scrollbar-hover#ee8877Scrollbar 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

#ee6655
#f2e0e8
#4a3f5c
#d9d2e3
#e8dada

Element Colors

#f2e0e8
#f7f3fa
#4a3f5c
#4a3f5c
#f2e0e8

Scrollbar

#ee6655
transparent
#ee8877

Border Radius

12px
12px
8px
6px
8px

Border Width

3px
3px
1px
1px

Spacing & Dimensions

1rem
0.5rem
24px
60px
60vh
/* 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;
  }
}