To add an icon font to a WordPress theme, bundle the licensed font files in your theme, define them with CSS @font-face, and load that CSS with wp_enqueue_style() on the wp_enqueue_scripts hook. Add editor-content styles separately when authors need to see the icons in the editor. For block-specific icons, associate a stylesheet with the block using wp_enqueue_block_style(); in a block theme, theme.json can expose a bundled web font as a typography option, but it does not create the icon classes or glyph mapping for you.
1. Prepare the font files and CSS
Use the file formats and glyph map supplied by your icon-font library. Keep the files inside the theme, for example:
your-theme/
├── assets/
│ ├── fonts/
│ │ ├── icons.woff2
│ │ └── icons.woff
│ └── css/
│ └── icons.css
└── functions.phpConfirm that your theme is allowed to redistribute the font files under the library’s current license. The library’s own CSS normally contains the correct family name, weight, Unicode values, and base class. If you write the rules yourself, preserve that mapping exactly.
/* assets/css/icons.css */
@font-face {
font-family: "MyTheme Icons";
src: url("../fonts/icons.woff2") format("woff2"),
url("../fonts/icons.woff") format("woff");
font-weight: normal;
font-style: normal;
font-display: swap;
}
.icon {
font-family: "MyTheme Icons";
font-style: normal;
font-weight: normal;
speak: never;
}
.icon-search::before { content: "\e900"; }
.icon-menu::before { content: "\e901"; }The content values above are examples only. Replace them with the code points from your selected library; using the wrong values produces empty or incorrect icons.
#1 Best Overall
2. Enqueue the stylesheet on the front end
WordPress describes wp_enqueue_style() as the function that “Enqueues a CSS stylesheet.” Register the stylesheet from functions.php on wp_enqueue_scripts rather than hard-coding a <link> element in the theme header.
function mytheme_enqueue_icon_font() {
wp_enqueue_style(
'mytheme-icons',
get_theme_file_uri( 'assets/css/icons.css' ),
array(),
wp_get_theme()->get( 'Version' )
);
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_icon_font' );The handle must be unique. get_theme_file_uri() resolves the file inside the active theme, and the theme version supplies a cache-busting value when you release an update. If the icon CSS depends on another stylesheet, add that stylesheet’s handle to the dependencies array instead of relying on load order.
3. Use the icon classes in markup
Apply the base class and the glyph class required by your mapping:
Rank #2
- Used Book in Good Condition
<span class="icon icon-search" aria-hidden="true"></span>For an icon-only button, the glyph is not an accessible name. Give the control a text label, an aria-label, or another appropriate accessible name:
Free tools Windows power users keep installed
One-click scans. No signup required.
<button type="button" aria-label="Open menu" class="menu-toggle">
<span class="icon icon-menu" aria-hidden="true"></span>
</button>If the icon conveys information rather than decoration, do not hide it from assistive technology without providing that information in text.
4. Decide how broadly to load the CSS
| Approach | Use it when | Implementation |
|---|---|---|
| Global theme stylesheet | The same icon rules are used across navigation, templates, widgets, or several blocks. | Enqueue the stylesheet on wp_enqueue_scripts. |
| Per-block stylesheet | The font rules belong only to one custom or core block. | Associate the CSS with that block using wp_enqueue_block_style(). |
WordPress documents both loading patterns, but the cited documentation does not establish a benchmark showing that one is always faster. Scope the stylesheet to the actual use case and avoid loading block-only rules globally when they are not needed elsewhere.
5. Make icons visible in the editor
Front-end assets and editor assets are separate concerns. If an icon appears inside edited content, add the corresponding content stylesheet for the editor:
// functions.php
add_editor_style( 'assets/css/icons.css' );For a block-specific implementation, use wp_enqueue_block_style() so the block’s stylesheet can be associated with editor and front-end rendering:
function mytheme_register_notice_block_style() {
wp_enqueue_block_style(
'mytheme/notice',
array(
'handle' => 'mytheme-notice-icons',
'src' => get_theme_file_uri( 'assets/css/notice-icons.css' ),
)
);
}
add_action( 'init', 'mytheme_register_notice_block_style' );Editor-content styles affect the content being edited; editor-interface assets affect the surrounding editing application. Choose the former for icon markup rendered in post content and the latter only when you are styling the editor interface itself.
6. Register a bundled font in a block theme’s theme.json (optional)
A block theme can describe a bundled web font under settings.typography.fontFamilies. This makes the family available as a typography choice. It is general web-font configuration, not an icon-font class generator.
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"typography": {
"fontFamilies": [
{
"fontFamily": "MyTheme Icons",
"slug": "mytheme-icons",
"fontFace": [
{
"fontFamily": "MyTheme Icons",
"fontStyle": "normal",
"fontWeight": "400",
"src": ["file:./assets/fonts/icons.woff2"]
}
]
}
]
}
}
}Keep the CSS containing your .icon-* selectors and glyph code points. If the font is purely an implementation detail and should not be selectable by authors, loading it through your stylesheet may be more appropriate than exposing it as a typography choice.
7. Classic themes, block themes, and child themes
Classic themes
Use the enqueue pattern in functions.php and load the icon CSS through wp_enqueue_scripts. This remains the standard approach for a front-end theme stylesheet.
Block themes
Use theme.json for supported style and typography configuration, while still using the enqueue APIs when a stylesheet must be loaded directly. A block-specific icon implementation can use wp_enqueue_block_style().
Child themes
Place the font files and CSS in the child theme when the child owns the icon implementation, and enqueue them from the child theme’s functions. If the parent already supplies the icon stylesheet, use its documented handle or dependency rather than loading a second copy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.8. Test the complete path
- Activate the intended theme and verify that the font files are present at the URLs generated from the theme asset path.
- View a page containing an icon and confirm that the icon stylesheet is enqueued and that the computed
font-familymatches the@font-facedeclaration. - Check the browser’s network and console output for incorrect paths, blocked font requests, or failed font decoding.
- Test every glyph used by the theme; a stylesheet can load correctly while an individual Unicode mapping is wrong.
- Open the block editor and confirm that icons in edited content use the editor-content stylesheet.
- Test the theme on each WordPress version you support, because the documented APIs do not substitute for testing your particular font and block registration.
9. Troubleshoot common failures
The icon area is blank
- Check that the CSS file URL and each relative font URL resolve under the active theme.
- Compare the declared family name with the family used by the icon selector.
- Verify the glyph’s Unicode value against the icon library’s mapping.
The font loads on the front end but not in the editor
Enqueueing on wp_enqueue_scripts covers the front end only. Add the editor-content stylesheet with add_editor_style() or associate the block stylesheet with wp_enqueue_block_style().
Only one block needs the icons
Move the selectors into that block’s stylesheet and register it with wp_enqueue_block_style() instead of making the rules global.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsIcons appear as text or squares
Inspect the loaded font format, family, weight, and code point. A missing glyph, a mismatched weight, or an unavailable font file can all produce a fallback character.
10. Consider SVG instead
WordPress supports custom SVG for block icons, and the core Icon block inserts SVG icons. SVG can be a better fit when the theme needs a small, selected set of icons in content rather than a broad reusable glyph font. It is not a universal replacement: choose based on how the icons are authored, reused, styled, and maintained in your theme.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
