Icon Selector Bundle

⭐ Found this useful? Install from Packagist · Give it a star on GitHub so more developers can find it.

Icon Selector Bundle — Symfony form type for selecting an icon with two modes: direct selector (grid) and search (filter by text). The value is stored as a string (e.g. heroicons-outline:home, bi:house). Configurable icon sets (Symfony UX Icons). For Symfony 7 and 8 · PHP 8.2+.

Table of contents

• Quick search terms
• Features
• Installation
• Usage
• Configuration
• Internationalization
• Documentation
• Requirements
• Demo
• Development
• License & author

Quick search terms

Looking for icon selector, icon picker, Symfony form icon, UX Icons form, Heroicons selector, Bootstrap Icons form, form type icon? You're in the right place.

Features

• ✅ IconSelectorType form type with mode: direct (grid of icons) or search (input + filtered list)
• ✅ Value is a single string (icon identifier compatible with Symfony UX Icons)
• ✅ Configurable icon sets in bundle config (e.g. heroicons, bootstrap-icons)
• ✅ API endpoint returns available icons (JSON) for the frontend; batch SVG endpoint (/svg) returns SVG markup for many icon IDs in one request (server uses ux_icon), so the selector avoids N individual requests when painting icons
• ✅ Form theme aligned with your app: set form_theme to match twig.form_themes (form_div, Bootstrap 5, etc.)
• ✅ Frontend: TypeScript + Vite; built script in Resources/public/ for assets:install
• ✅ Demos (Symfony 7 and 8) with both selector types, persisting the chosen icon string
• ✅ Demos run with FrankenPHP (Caddy, HTTP on port 80 in the container). Default APP_ENV=dev uses Caddyfile.dev (no PHP worker so template/PHP changes show on refresh). Worker mode applies to a production-style setup — see docs/DEMO-FRANKENPHP.md
• ✅ Internationalizable: uses Symfony Translation; domain NowoIconSelectorBundle for placeholder, search placeholder and choice labels; override with translation_domain and search_placeholder options

Installation

composer require nowo-tech/icon-selector-bundle

With Symfony Flex, the recipe (if available) registers the bundle and adds config. Without Flex, see docs/INSTALLATION.md for manual steps.

Manual registration in config/bundles.php:

<?php

return [
  // ...
  Nowo\IconSelectorBundle\NowoIconSelectorBundle::class => ['all' => true],
];

Usage

1. Add the field to your form with IconSelectorType::class and option mode: 'direct', 'search', or 'tom_select'.
2. Load the widget in one of two ways (see Usage → Frontend for details):

• Option A (normal JS): Include the bundle script in your layout: {{ asset(nowo_icon_selector_asset_path('icon-selector.js')) }}. Run php bin/console assets:install once. The script initializes all icon selectors on load and any injected later (MutationObserver).
• Option B (Stimulus controller): If your app uses Stimulus, register the bundle's icon-selector controller. No script tag needed; your JS bundle includes the lib. For tom_select mode, load Tom Select CSS in your app.

3. The submitted value is a string (e.g. heroicons-outline:home). Render it with {{ ux_icon(entity.icon) }} (Symfony UX Icons is a required dependency).

Example:

use Nowo\IconSelectorBundle\Form\IconSelectorType;

$builder->add('icon', IconSelectorType::class, [
  'mode' => 'direct', // or 'search'
  'label' => 'Choose an icon',
]);

Full details: docs/USAGE.md.

Configuration

Create config/packages/nowo_icon_selector.yaml (or rely on defaults). Options:

• icon_sets: list of icon libraries (e.g. heroicons, bootstrap-icons). Only these are available in the selector.
• use_iconify_collection: when true, the selector loads the full icon list from api.iconify.design for each library (requires symfony/http-client). When false, a small built-in list is used.
• icons_api_path: URL path for the JSON icon list API (default: /api/icon-selector/icons). Must match the route the bundle exposes (see CONFIGURATION.md).
• form_theme: base form layout so the icon selector theme matches your app (e.g. form_div_layout.html.twig, bootstrap_5_layout.html.twig). Must match the same value you use in twig.form_themes.
• debug: when true, the frontend logs detailed messages to the browser console; when false (default), only a short “script loaded” line.

Full options: docs/CONFIGURATION.md.

Internationalization

The bundle uses Symfony’s Translation component. All user-facing strings (placeholder, search input placeholder, and choice labels in the dropdown) are translated via the domain NowoIconSelectorBundle.

• Included translations: Resources/translations/NowoIconSelectorBundle.en.yaml and NowoIconSelectorBundle.es.yaml (placeholder, search_placeholder, and common icon names).
• Override or add locales: copy the YAML files into your app’s translations/ and customize, or add new locale files with the same domain.
• Per-field options: you can set translation_domain (e.g. 'messages' or false to disable) and search_placeholder (string or translation key) when adding the field.

$builder->add('icon', IconSelectorType::class, [
  'mode'        => 'tom_select',
  'translation_domain'  => 'messages', // use your app domain
  'placeholder'     => 'my.placeholder.key',
  'search_placeholder'  => 'my.search.placeholder',
]);

Documentation

• Installation
• Configuration
• Usage
• Contributing
• Changelog
• Upgrading
• Release
• Security
• Engram

Additional documentation

• Overriding bundle templates
• Demo with FrankenPHP (development and production) — development vs production setup, Web Profiler, Twig Inspector; reusable for other bundles

Requirements

• PHP >= 8.2, < 8.6
• Symfony ^7.0 || ^8.0
• symfony/ux-icons ^1.0 || ^2.0 (required; used to render icons via ux_icon() in Twig)
• For building assets (developers): Node.js, pnpm, Vite — see Development

Demo

Demos (Symfony 7 and 8) are in demo/symfony7 and demo/symfony8. Each uses FrankenPHP with Caddy (HTTP on port 80 inside the container). docker-compose sets APP_ENV=dev: the entrypoint uses Caddyfile.dev (no PHP worker), so edits to Twig/PHP are visible on refresh. A production-style stack uses the default Caddyfile with worker mode — see docs/DEMO-FRANKENPHP.md. Each demo shows icon selector fields (grid, search, Tom Select, Heroicons); the chosen icon strings are stored in session.

Grid (direct)	Tom Select

Host ports: Symfony 7 demo defaults to 8010, Symfony 8 to 8011 (PORT in each demo’s .env). Access is HTTP (no HTTPS) mapped from the host to port 80 in the container.

From the bundle root:

make -C demo/symfony8 up
# or make -C demo/symfony7 up
# Open http://localhost:8011 (symfony8) or http://localhost:8010 (symfony7), unless PORT is overridden

See docs/DEMO-FRANKENPHP.md for development vs production setup (worker mode, Twig cache, OPcache).

Development

Run tests and QA with Docker: make up && make install && make test (or make test-coverage, make qa). Without Docker: composer install && composer test.

• PHP-CS-Fixer: make cs-check / make cs-fix
• Rector: make rector / make rector-dry
• PHPStan: make phpstan
• release-check: cs-fix, cs-check, rector-dry, phpstan, test-coverage

Building assets (TypeScript + Vite): make assets (runs pnpm install and pnpm run build in the container) or locally: pnpm install && pnpm run build. Watch mode: make assets-watch or pnpm run watch. TypeScript unit tests (Vitest): make assets-test or pnpm run test.

Tests and coverage

• Tests: PHPUnit (PHP), Vitest (TS/JS)
• PHP: 99.25%
• TS/JS: 100%

License

The MIT License (MIT). Please see LICENSE for more information.

Author

Created by Héctor Franco Aceituno at Nowo.tech