Download the PHP package nowo-tech/icon-selector-bundle without Composer

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+.

This bundle is FrankenPHP worker mode friendly.

Table of contents

• Quick search terms
• Features
• Installation
• Requirements
• Configuration
• Usage
• Internationalization
• Demo
• Development
• Documentation
• Tests and coverage
• 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
• ✅ Demo (Symfony 8) with both selector types, persisting the chosen icon string
• ✅ Demo runs 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

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:

Requirements

• PHP >= 8.2, < 8.6
• Symfony ^6.4 || ^7.0 || ^8.0
• symfony/ux-icons ^2.17 || ^3.0 (required; 3.x needs PHP 8.4+ and Symfony 7.4+; used to render icons via ux_icon() in Twig)
• For building assets (developers): Node.js, pnpm, Vite — see Development

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.

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('icon-selector.js', 'nowo_icon_selector') }} or {{ asset(nowo_icon_selector_asset_path('icon-selector.js'), 'nowo_icon_selector') }}. 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:

Full details: docs/USAGE.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, .es.yaml, .de.yaml, .fr.yaml, .it.yaml, .nl.yaml, and .pt.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.

Demo

The demo is in demo/symfony8. It 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. The demo shows icon selector fields (grid, search, Tom Select, Heroicons); the chosen icon strings are stored in session.

Host port: defaults to 8011 (PORT in the demo’s .env). Access is HTTP (no HTTPS) mapped from the host to port 80 in the container.

From the bundle root:

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, make igor
• 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.

Documentation

• GitHub Actions CI requirements
• Installation
• Configuration
• PSR evaluation (REQ-CS-007)
• Usage
• Contributing
• Code of Conduct
• Changelog
• Upgrading
• Release
• Security
• FrankenPHP worker audit
• Engram
• Spec-driven development
• GitHub Spec Kit

Additional documentation

• Overriding bundle templates
• Demo with FrankenPHP (development and production) — development vs production setup, Web Profiler, Twig Inspector; reusable for other bundles
• FrankenPHP worker audit (scenario B, no kernel reset)

Tests and coverage

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

License

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

Author

Created by Héctor Franco Aceituno at Nowo.tech