metaory/iconify-picker

Zero-dependency icon picker with built-in UI modes and native events

Summary

Iconify Picker is a zero-dependency, framework-agnostic web component that wraps the Iconify icon library into a searchable picker UI. It ships as a single JavaScript file that registers a custom <iconify-picker> element, with modes for inline embedding, button-triggered popups, and manual programmatic control.

What it is useful for

This component solves the problem of letting end users pick an icon inside an application — for example, letting a CMS user choose a category icon, a dashboard builder select a sidebar glyph, or a settings panel attach an icon to a label. Because it depends only on Iconify at runtime, with no framework dependency in the package itself, it can be dropped into vanilla HTML, a static site, or a framework project with minimal coupling. It exposes the picked icon as an SVG string along with metadata, which is convenient when you need to persist the selection or render the icon elsewhere.

How engineers can use it

Install via npm or pnpm, or load directly from a CDN:

npm install iconify-picker
# or
pnpm add iconify-picker

Then import it as a side effect to register the element:

import 'iconify-picker'

Drop the element into your markup with at least a collection attribute (e.g., mdi, lucide, tabler, heroicons):

<iconify-picker collection="mdi"></iconify-picker>

Three modes are documented. inline renders the picker visibly on the page. mode="button" collapses it into a labeled trigger:

<iconify-picker mode="button" button-label="Choose Icon" collection="lucide"></iconify-picker>

mode="manual" starts hidden and is controlled with the .show(), .hide(), .toggle(), .reset(), and .focus() methods, which is useful when the picker should open from your own UI.

The component fires an icon-selected event whose detail includes iconName, collection, name, and svg. A change event with the same payload is also emitted for form-style integrations. Optional attributes let you adjust behavior: theme (light, dark, auto), page-size, selected, height, filter, search, hide-search, and hide-collection.

Appearance is controlled through --picker-* CSS custom properties and shadow parts (container, header, footer, search, select, grid, icon, icon-image, button, pagination) for targeted overrides.

Documented limitations: the README does not describe a server-side rendering entry, TypeScript type definitions, or a non-JS distribution. Engineers using SSR or strongly typed codebases should verify those scenarios against the docs site and the examples/vanilla/index.html example before adopting it.