Spectre Icons

Spectre Icons is a WordPress plugin that adds bundled and uploaded SVG icon libraries to Elementor's icon picker, with per-library enable/disable controls. Icons render as inline SVG so they inherit theme colors through builder color controls, and uploaded icons are sanitized and stored in a site-sp

This page is generated from the source repository’s README and ROADMAP on every build. Edit the source repository, not this file.

README

Spectre Icons

Spectre Icons is a WordPress plugin that adds bundled and uploaded SVG icon libraries to Elementor’s icon picker, with per-library enable/disable controls. Icons render as inline SVG so they inherit theme colors through builder color controls, and uploaded icons are sanitized and stored in a site-specific My Icons library.

Maintained by PHCDevworks. It ships bundled SVG icon libraries (Lucide and Font Awesome Free) and per-library enable/disable controls for Elementor’s icon picker today, with the architecture built to support additional page builders as they’re added.

Repository Snapshot

Field Value
Project team project-plugins
Repository role WordPress and Elementor icon-library plugin
Package/artifact spectre-icons
Current version/status 1.5.0

Standard Workflow

  1. Read AGENTS.md, then the agent-specific guide for the task.
  2. Check TODO.md and ROADMAP.md for current scope.
  3. Make the smallest repo-local change that satisfies the task.
  4. Run npm run check when validation is required or practical.
  5. Update docs and CHANGELOG.md only when behavior, public contracts, or release-relevant metadata changed.

Documentation Map

Guide Path
Agent rules AGENTS.md
Claude Code CLAUDE.md
Codex CODEX.md
Copilot COPILOT.md
Jules JULES.md
Roadmap ROADMAP.md
Todo TODO.md
Changelog CHANGELOG.md
Security SECURITY.md

CI GitHub issues GitHub pulls License

Spectre Icons adds Lucide, Font Awesome Free, and your own uploaded SVG icons to Elementor’s icon picker as inline SVG. Libraries can be enabled or disabled individually from plugin settings. Disabled libraries are hidden from the picker — icons already placed on your site keep rendering.

Contributing | Changelog | Security Policy | WordPress Plugin Directory

When to use this plugin

Use Spectre Icons if:

  • You are building WordPress sites with Elementor and want Lucide or Font Awesome Free in the icon picker.
  • You want icons to render as inline SVG so they inherit theme colors through Elementor’s color controls without a separate font file.
  • You want to enable or disable icon libraries individually without touching icons already placed on your site.
  • You want a site-specific My Icons library for sanitized SVG uploads.

Do not use Spectre Icons if:

  • You are not using Elementor — Gutenberg, Divi, and other builder support is planned but not yet available.
  • You need custom icon fonts, CSS-class icon libraries, sprite-based rendering, or bulk third-party icon-pack management.

Features

  • Manifest-driven icon library registration — no scattered builder-specific definitions
  • Inline SVG rendering in both editor preview and frontend
  • Enable or disable individual icon libraries from plugin settings
  • Upload custom SVG files to a site-specific My Icons library
  • Disabled libraries are hidden from the picker; existing icons keep rendering
  • Theme-friendly color inheritance through builder color controls
  • Modular architecture for future builder support

Installation

WordPress admin

  1. Go to Plugins -> Add New
  2. Search for Spectre Icons
  3. Click Install Now, then activate
  4. Open Settings -> Spectre Icons

Manual

  1. Download the plugin ZIP
  2. Go to Plugins -> Add New -> Upload Plugin
  3. Upload, activate, then open Settings -> Spectre Icons

From source

git clone https://github.com/phcdevworks/spectre-icons.git
cd spectre-icons
composer install
bin/lint-php.sh

Usage

Go to Settings -> Spectre Icons and enable the libraries you want. Use Settings -> My Icons to upload site-specific SVG icons. Then open any Elementor widget that has an icon field and choose a Spectre Icons tab from the picker.

Supported widgets include Icon, Icon Box, Icon List, and Social Icons.

Included icon libraries

  • Lucide Icons
  • Font Awesome Free
  • My Icons, a site-specific library for uploaded SVG files

The bundled SVG files are locked source assets. Registration, rendering, and admin controls can evolve but the bundled icon files themselves are not modified as part of normal development.

Requirements

  • WordPress 6.0+, tested up to 7.0
  • PHP 7.4+
  • Elementor 3.x / 4.x, tested through Elementor 4.x

Development

Local setup

git clone https://github.com/phcdevworks/spectre-icons.git
cd spectre-icons
composer install   # installs PHPUnit and PHPCS
npm install        # installs Playwright and wp-env

Full validation (mirrors CI)

npm run check       # composer validate + composer test + composer lint
npm run check:full  # PHP checks + Playwright smoke, Elementor, and My Icons e2e

Individual commands

bin/lint-php.sh          # PHP lint (PHPCS)
composer lint            # PHP lint via Composer script
composer test            # PHPUnit — no WordPress environment required

E2E tests (requires a running WordPress + Elementor environment)

npm run test:e2e:setup      # start wp-env, install pinned Elementor, activate Spectre Icons
npm run test:e2e            # full Playwright suite
npm run test:e2e:smoke      # activation and settings check
npm run test:e2e:elementor  # icon picker and rendering flows
npm run test:e2e:my-icons   # uploaded icon picker, editor preview, and frontend flows
npm run wp-env:stop         # stop the local environment

Optional environment variables for remote WP targets:

  • SPECTRE_E2E_BASE_URL
  • SPECTRE_E2E_ADMIN_USER
  • SPECTRE_E2E_ADMIN_PASSWORD

Troubleshooting

Icons don’t appear in the Elementor picker after installation Go to Settings → Spectre Icons and confirm the library is enabled. Then go to Elementor → Tools → Regenerate Files & Data to flush the editor cache.

Blank icon previews in the Elementor editor after a plugin update The plugin flushes its editor cache on the first admin load after an update. If blank icons persist, go to Elementor → Tools → Regenerate Files & Data.

PHPUnit fails with class-not-found errors Run composer install to install dev dependencies before running tests.

npm run check fails on composer validate Run composer install to bring composer.lock in sync before validating.

Contributing

Keep contributions focused on icon-library expansion for builders. Treat bundled SVG files as locked assets. See CONTRIBUTING.md for the full workflow.

License

Plugin code is GPL-2.0-or-later. See LICENSE.

Bundled icon libraries retain their upstream licenses:

  • Lucide — ISC
  • Font Awesome Free — icons CC BY 4.0, code MIT

Roadmap

ROADMAP.md

Spectre Icons Roadmap

Spectre Icons is a focused WordPress plugin that expands native icon-library support for site builders. It registers curated SVG icon libraries inside builder icon pickers and renders them as inline SVGs on the frontend. Its job is to solve the icon-fragmentation problem cleanly, without becoming a general design system or site-builder framework.

1. Foundation Status - Delivered

All foundation work is complete as of v1.5.0. The plugin is stable and in active use.

What is in place

  • Manifest-driven icon library registration with no scattered builder-specific definitions.
  • Inline SVG rendering in both Elementor editor preview and frontend.
  • Per-library enable/disable controls with picker hiding and graceful fallback for already-placed icons.
  • Lucide Icons (1545 icons) and Font Awesome Free bundled as locked source assets.
  • My Icons — a site-specific, unlimited-by-default user upload library (spectre-user slug, spectre-user- prefix) with file-based SVG storage, an admin upload/delete page, and a one-time migration from the legacy 1.4.x inline-manifest format.
  • Builder-agnostic core (includes/core/) with Elementor adapter in includes/elementor/.
  • SVG sanitizer using DOM traversal with an explicit tag and attribute allowlist.
  • PHP unit tests with no real WordPress environment required.
  • Playwright end-to-end tests for activation, settings, icon picker, My Icons uploads, and rendering flows.
  • CI pipeline running full validation on every push and pull request.
  • Serialization-safe library slugs and class prefixes locked and protected.
  • Elementor file cache flush on first admin load after version bump.
  • Multi-agent team (Claude Code, Codex, Copilot, Jules) with documented authority boundaries and PR requirements.

What will not change

  • Serialization-anchored slugs (spectre-lucide, spectre-fontawesome) and class prefixes are permanent. Changing them breaks saved icons on active installs.
  • Bundled SVG source assets are locked. Registration, rendering, and admin controls can evolve; the icon files do not.
  • Builder-agnostic core (includes/core/) stays free of page-builder imports.
  • Elementor-specific logic stays inside includes/elementor/.

2. Roadmap - Mature Phase

The foundation is stable. The next phase strengthens the Elementor integration, adds support for additional builders, and improves the icon-library onboarding experience.

P0: Elementor Integration Hardening

Objective Ensure the Elementor integration is robust, well-tested, and ready to serve as the model for future builder adapters.

Why it matters Elementor is the active builder. Strengthening it before adding new builder targets avoids compounding technical debt across multiple integration paths.

Deliverables

  • Close any known gaps in E2E test coverage for icon picker, rendering, and settings flows.
  • Validate editor preview behavior across Elementor 3.x and 4.x.
  • Document any Elementor-specific extension points or lifecycle dependencies that future adapters must account for.
  • Confirm that the adapter boundary between includes/core/ and includes/elementor/ is clean enough to serve as the template for a second builder.

P1: Additional Builder Support

Objective Add support for at least one additional WordPress builder to reduce dependency on Elementor and expand the plugin’s user base.

Why it matters The plugin’s architecture is explicitly designed for multiple builders. Proving that design with a second integration validates the approach and increases the plugin’s value.

Candidate builders (in rough priority order):

  • Gutenberg / block editor
  • Bricks
  • Beaver Builder
  • Divi
  • Oxygen

Deliverables

  • Select the next builder target based on user demand and integration complexity.
  • Implement a new adapter in the pattern of includes/elementor/, keeping all builder-specific logic contained.
  • Add E2E coverage for the new builder’s icon picker and rendering flows.
  • Document the new builder’s setup and compatibility requirements.

Dependency notes

  • Requires clean adapter boundary from P0 before starting.

P2: Icon Library Expansion

Objective Add one or more additional curated icon libraries to increase the plugin’s value without increasing maintenance complexity.

Why it matters More icon options increase site-builder flexibility and reduce the need for competing plugins. Manifest-driven registration makes adding libraries low-risk.

Deliverables

  • Evaluate candidate libraries for quality, license compatibility, and downstream demand.
  • Add new libraries as bundled manifests with appropriate serialization-safe slugs and class prefixes.
  • Document any new slugs in the anchored registry.

Candidates (not committed):

  • Phosphor Icons
  • Tabler Icons
  • Heroicons

P3: Pro Features

Objective Introduce paid capabilities to support the plugin’s long-term sustainability.

Why it matters Free tier remains fully functional. Pro tier unlocks features that demand ongoing investment.

Candidate pro capabilities:

  • Per-page or per-post library scoping
  • Font Awesome Pro bring-your-own-license integration (see TODO.md P3 for the three candidate approaches)

Dependency notes

  • Requires a clear commercial delivery path from Bradley Potts before implementation begins.
  • Custom icon library registration and user-supplied SVG import already shipped free-tier as My Icons (v1.3.0-v1.5.0) — do not re-propose these as pro candidates.

3. Explicitly Out of Scope

  • General design system or component framework behavior.
  • Theme frameworks or site-building abstractions beyond icon-library support.
  • App-shell orchestration or Spectre ecosystem infrastructure.
  • Unrelated WordPress features.
  • Bulk modification or regeneration of bundled SVG source files.
  1. P0 - Elementor hardening - complete the active integration before adding a second builder.
  2. P1 - Additional builder - validate the multi-builder architecture with a second adapter.
  3. P2 - Icon library expansion - grow the library catalog after the builder support model is proven.
  4. P3 - Pro features - only after the free-tier product is mature and a commercial delivery path is confirmed.