GitHub

Iconify Picker

Iconify Picker

An autonomous web component for selecting icons from the Iconify project.

Iconify Picker is a lightweight, dependency-free web component that allows you to easily integrate icon selection functionality into your web applications.

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

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)

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:

  • dark Detecting the class on the HTML element
  • theme Observing 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

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-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-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
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-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;
  }
}