CKEditor 5 Icons: A fast & native Font Awesome icon picker
A fast and native Font Awesome icon picker for CKEditor 5, enabling users to browse, search, and insert icons directly within the editor.
ckeditor5_icons
Install
composer require 'drupal/ckeditor5_icons:^1.2'
Overview
CKEditor 5 Icons is a powerful module that integrates Font Awesome icons directly into the CKEditor 5 editing experience. Built using CKEditor 5's modern TypeScript APIs, it provides a seamless icon picker that allows content editors to browse, search for, and select Font Awesome icons without ever leaving the editor interface.
The module supports both Font Awesome 5 and Font Awesome 6, including free and Pro versions. Icons can be inserted inline with text, and their size, style, and alignment can be easily modified using a convenient widget toolbar that appears when an icon is selected. The icon picker features category filtering, real-time search, and a customizable "Recommended" category for frequently used icons.
Performance is optimized through asynchronous metadata loading, which reduces initial page load times by only fetching icon data when the picker is opened. The metadata is also cached by browsers for subsequent requests.
Features
- Native Font Awesome icon picker integrated directly into CKEditor 5 toolbar
- Support for both Font Awesome 5 (v5.15.4) and Font Awesome 6 (v6.7.2)
- Browse icons by categories or search by icon name and keywords
- Widget toolbar for modifying icon size, style, and alignment after insertion
- 14 size options from Extra Small to 10x
- 3 alignment options: inline with text, pull left, or pull right
- 7 style options: Solid, Regular, Light, Thin, Duotone, Brands, and Custom (Pro styles require Font Awesome Pro)
- Configurable "Recommended" category for quick access to frequently used icons
- Asynchronous metadata loading for optimized page performance with browser caching
- Integration with the Font Awesome Icons module for custom/Pro metadata
- Icons output as standard HTML <i> elements with Font Awesome classes
- Full compatibility with General HTML Support and Link plugins
Use Cases
Adding icons to content
Content editors can click the Icons button in the CKEditor 5 toolbar to open the icon picker. They can browse icons by category, search by name or keywords, and click to insert the selected icon at the cursor position. Icons are inserted inline with text.
Styling icons after insertion
After inserting an icon, clicking on it reveals a widget toolbar with dropdown menus for changing the icon's size (Extra Small through 10x), alignment (inline, pull left, pull right), and style (Solid, Regular, Brands, etc.).
Creating a list of recommended icons
Site administrators can configure a Recommended category in the text format settings to provide quick access to frequently used icons. This is useful for maintaining consistent iconography across content.
Using Font Awesome Pro icons
Sites with Font Awesome Pro can install the Font Awesome Icons contrib module and set the metadata source to Custom in the Icons plugin configuration. This enables access to Pro-only styles like Light, Thin, and Duotone.
Optimizing page load performance
By default, icon metadata is loaded asynchronously when the picker is first opened, rather than on every page load. This significantly reduces initial page size and is recommended for production sites.
Tips
- Use the search feature in the icon picker to quickly find icons by name or related terms
- Icons can be placed inside links by first inserting the icon, then selecting it and using the link button
- For better performance, keep the 'Load metadata asynchronously' option enabled in production
- The Recommended category is useful for creating a curated set of brand-approved icons for content editors
- Icons use standard Font Awesome CSS classes, so any Font Awesome theme customizations will apply automatically
Technical Details
Admin Pages 1
/admin/config/content/formats/manage/{format_id}
Configure the CKEditor 5 Icons plugin settings within a text format's CKEditor 5 configuration. The Icons plugin settings appear when you add the Icons button to the toolbar.
Troubleshooting 4
Ensure the Font Awesome CSS library is properly loaded on your site. This can be done via your theme's CSS, a CDN link, or the Font Awesome Icons contrib module. The selected version in the plugin settings must match the loaded library version.
Install and configure the Font Awesome Icons contrib module, then set the metadata source to 'Custom' in the Icons plugin settings. Ensure your Font Awesome Pro kit or CSS is properly loaded.
Try disabling 'Load metadata asynchronously' in the plugin settings as a troubleshooting step. Check browser console for CSRF token errors or network issues with the metadata endpoint.
This can occur if the icon name is not recognized in the metadata. Ensure the icon exists in the selected Font Awesome version and that metadata is loading correctly.