How to Fix Bootstrap Icons Not Showing

SoftwareRoad Knowledge Base can display Bootstrap Icons across categories, articles and homepage highlights.

If an icon field contains a valid class but no icon appears publicly, the cause is usually one of the following:

• The icon class is incorrect
• A custom uploaded image is taking priority
• The Bootstrap Icons CDN is blocked
• A firewall or Content Security Policy is preventing the files from loading
• A browser extension is blocking the external resource
• Caching or optimisation is serving an incomplete stylesheet

Work through the checks below in order.

Check the icon class format

Bootstrap icon classes used by SoftwareRoad Knowledge Base should begin with:

bi-

For example:

bi-book

bi-search

bi-key

bi-tools

bi-gear

Enter only the individual icon class in the field.

Correct icon class example

Use:

bi-book

Do not use:

book

bootstrap-book

icon-book

<i class="bi bi-book"></i>

bi bi-book

SoftwareRoad Knowledge Base creates the required icon markup automatically.

The setting only needs the individual bi- icon class.

Check for spelling mistakes

A single missing letter or hyphen can prevent an icon from appearing.

For example:

Correct:

bi-file-earmark-text

Incorrect:

bi-file-earmarktext

Correct:

bi-shield-check

Incorrect:

bi-shieldcheck

Delete the field contents and type the class again carefully.

Remove accidental spaces

Extra spaces can stop the icon class from being recognised properly.

Incorrect:

bi-book

Incorrect:

bi-book

Correct:

bi-book

Click at the beginning and end of the field and remove any blank spaces.

Test with a simple icon

Use a common icon class to check whether Bootstrap Icons are loading at all.

Try:

bi-book

or:

bi-search

Save the article, category or homepage setting and check the public knowledge base.

If a simple icon appears, the original class was probably incorrect or unavailable.

Check the category icon setting

For a category icon:

1. Open Knowledge Base > Categories.
2. Edit the affected category.
3. Find the Bootstrap icon field.
4. Enter a valid class such as:

bi-folder

5. Select Update.
6. Open the main knowledge base page.
7. Check the category card.

Make sure you are editing the same category that appears publicly.

Check the article icon setting

For an article icon:

1. Open Knowledge Base > All Articles.
2. Edit the affected article.
3. Find the article icon setting.
4. Enter a valid Bootstrap icon class.
5. Select Update.
6. Check the article in search results and category lists.

Article icons may not appear in every layout, so check more than one location.

Check the homepage highlight icon

For homepage highlights:

1. Open Knowledge Base > Settings.
2. Select the Homepage tab.
3. Find the Homepage Highlights section.
4. Check the icon class for each highlight.
5. Select Save Changes.
6. Clear the homepage cache.
7. Reload the main knowledge base page.

Make sure the Homepage Highlights section itself is enabled.

Custom uploaded images take priority

If both a Bootstrap icon class and an uploaded custom image are saved, the custom image takes priority.

This means the Bootstrap icon may be saved correctly but hidden because an image is being used instead.

This can affect:

• Category icons
• Article icons
• Homepage highlight icons

Remove the custom image

To show the Bootstrap icon again:

1. Edit the category, article or highlight.
2. Find the custom image field.
3. Remove the uploaded image.
4. Confirm the Bootstrap icon class is still present.
5. Save or update the item.
6. Clear the page cache.
7. Check the public knowledge base.

The icon should appear once the custom image no longer overrides it.

The image field looks empty but still has an attachment

In some cases, a media field may still contain a saved attachment even if the preview is not obvious.

Select any available Remove or Clear button.

Then save the item again.

If needed, choose another image temporarily, save it, remove it and save once more.

This can clear an old attachment value.

Check whether the icon appears in another location

An article icon may appear in one layout but not another.

For example, it may appear in:

• Search results
• Category article lists
• Recommended Articles

but not in a particular sidebar panel.

This can depend on whether that section is designed to show icons.

Check the areas where icons are normally supported before assuming the icon is broken.

Check the icon size

An icon may be present but too small to notice.

Open:

Knowledge Base > Settings > Design

Check:

• Category Icon Size
• Article Icon Size
• Highlight Icon Size, where available

Increase the size slightly and save the settings.

Do not make the icon excessively large simply to compensate for another display issue.

Check the icon colour

The icon may be loading but using the same colour as its background.

For example:

• White icon on a white card
• Dark icon on a dark sidebar
• Pale grey icon on a light grey background
• Transparent-looking icon caused by low contrast

Open the Design settings and temporarily choose a clearly different icon colour.

If the icon becomes visible, adjust the final colour to provide better contrast.

Inspect the page source

Advanced users can inspect the icon with browser developer tools.

Right-click near the missing icon and select Inspect.

Look for an element containing a class similar to:

bi-book

If the icon element exists but nothing is visible, the Bootstrap Icons stylesheet may not be loading.

If the element does not exist, check the saved icon field, image priority and current layout.

Bootstrap Icons are loaded from a CDN

SoftwareRoad Knowledge Base loads Bootstrap Icons from the Bootstrap Icons CDN through jsDelivr.

This means the visitor’s browser must be able to reach the external stylesheet and font files.

If jsDelivr is blocked, the icon elements may appear in the page source but no visible icon will be rendered.

Check whether jsDelivr is accessible

Open the browser developer tools and select the Network tab.

Reload the knowledge base page.

Search the requests for:

jsdelivr

or:

bootstrap-icons

Look for the Bootstrap Icons stylesheet and font files.

A successful request normally shows a response status such as:

200

A failed or blocked request may show:

• 403
• 404
• ERR_BLOCKED_BY_CLIENT
• ERR_CONNECTION_REFUSED
• Content Security Policy errors
• Failed DNS resolution

All icons are missing

If every Bootstrap icon is missing across the knowledge base, the CDN stylesheet is probably not loading.

Check:

• Browser Console
• Network requests
• Firewall rules
• Content Security Policy
• Ad-blocking extensions
• Privacy extensions
• CSS optimisation
• External resource restrictions

A wrong icon class usually affects only one icon.

A blocked stylesheet affects all Bootstrap Icons.

One icon is missing

If other Bootstrap Icons work but one does not, check:

• Exact class spelling
• Whether the icon exists in the loaded Bootstrap Icons version
• Extra spaces
• Whether a custom image overrides it
• Whether the item was saved
• Whether the affected page is cached

Try replacing it with:

bi-book

If the replacement works, choose another valid icon class.

Check the browser console

Open the browser developer tools and select the Console tab.

Reload the page and look for errors relating to:

• jsDelivr
• Bootstrap Icons
• Font files
• Content Security Policy
• Mixed content
• Cross-origin requests
• Blocked stylesheets

Copy the exact error message before making changes.

Content Security Policy blocks the icons

A Content Security Policy can restrict where stylesheets and fonts are loaded from.

The browser console may show wording such as:

• Refused to load the stylesheet
• Refused to load the font
• Violates the following Content Security Policy directive

The policy may need to allow the required jsDelivr resources.

Depending on the policy, this can involve directives such as:

• style-src
• font-src
• style-src-elem

Only change Content Security Policy rules if you understand the website’s security setup.

Use the narrowest allowance needed.

Do not disable the full Content Security Policy

A Content Security Policy helps protect the website.

Do not remove the entire policy simply to make icons appear.

Instead:

1. Identify the exact blocked jsDelivr resource.
2. Confirm it belongs to Bootstrap Icons.
3. Add the required trusted source to the relevant directive.
4. Reload the page.
5. Check the browser console again.

Ask your hosting provider or developer for help where needed.

Hosting firewall restrictions

A hosting firewall may block outgoing or visitor access to external CDN resources.

This is more common on:

• Restricted business networks
• School or public-sector networks
• Security-focused hosting
• Websites using strict proxy rules
• Internal intranet environments

Ask the hosting provider or network administrator whether jsDelivr is blocked.

Do not send them your SoftwareRoad licence key.

Web application firewall rules

A web application firewall may block external styles or fonts based on:

• Domain reputation rules
• Geographic restrictions
• File types
• Cross-origin requests
• Strict security profiles

Review the firewall event log while loading the affected page.

Look for blocked requests involving the jsDelivr domain.

DNS filtering

Some networks use DNS filtering to block content delivery networks.

If icons work on one connection but not another, test using:

• Another Wi-Fi network
• Mobile data
• Another device
• A different office network

If the issue only happens on one network, local filtering may be responsible.

Ad-blocking extensions

Browser extensions can block CDN files.

The browser Network tab may show:

ERR_BLOCKED_BY_CLIENT

This often means a browser extension prevented the request.

Test the page in:

• A private window
• Another browser
• A browser with extensions disabled
• Another device

Some extensions remain active in private browsing, so check the extension settings as well.

Privacy extensions

Privacy extensions may block:

• External stylesheets
• Third-party font files
• Content delivery networks
• Cross-site requests

If Bootstrap Icons fail only for one user or one browser, extensions are a likely cause.

The website itself may be functioning correctly for most visitors.

Browser tracking protection

Strict browser tracking protection can sometimes block third-party resources.

Test with the browser’s standard protection level.

Do not ask visitors to disable their full browser protection permanently.

An uploaded local custom icon may be a better alternative where external CDN access is unreliable.

Use an uploaded image as an alternative

SoftwareRoad Knowledge Base allows custom images to be used instead of Bootstrap Icons.

To use one:

1. Edit the category, article or homepage highlight.
2. Upload a suitable icon image.
3. Save the item.
4. Clear the cache.
5. Check the public page.

The uploaded image takes priority over the Bootstrap icon class.

This avoids relying on the external Bootstrap Icons CDN for that item.

Choose suitable custom icon files

Good custom icon files include:

• Transparent PNG
• WebP with transparency
• SVG where safely supported by your WordPress setup

Use images with:

• Similar dimensions
• Consistent visual style
• Minimal empty space
• Clear shapes
• Small file sizes

Avoid uploading very large photographs as small knowledge base icons.

Local images and privacy

Using an uploaded custom image means the file is normally served from your own WordPress media library.

This can be useful where:

• External resources are blocked
• The website has a strict Content Security Policy
• You want fully branded icons
• You prefer not to load the Bootstrap Icons CDN

Uploaded images require more manual management than Bootstrap icon classes.

Check WordPress caching

A cached page may continue showing the old icon or no icon.

Clear:

• WordPress page cache
• Object cache
• Hosting cache
• Server cache
• CDN cache
• Browser cache

Then open the page in a private browser window.

Clear the exact affected page

If only one category or article icon is missing, clear the cache for that specific URL.

For example:

• Main knowledge base homepage
• Affected category page
• Affected article page

Some caching systems store each page separately.

Check CDN page caching

A website CDN may cache the HTML before the icon class was added.

Purge the affected page URL.

This is separate from the Bootstrap Icons CDN itself.

Your website CDN may be serving old HTML, while jsDelivr is serving the icon files correctly.

CSS optimisation can remove the icon stylesheet

Performance plugins may remove or combine the Bootstrap Icons stylesheet.

Features that can cause problems include:

• Remove unused CSS
• Combine CSS
• Delay CSS
• Asynchronous stylesheet loading
• Critical CSS generation
• CSS minification
• External stylesheet removal

Temporarily disable these features and clear all caches.

Removed unused CSS

An optimisation service may incorrectly decide that the Bootstrap icon classes are unused.

This can happen when classes are added dynamically or only appear on certain knowledge base pages.

If disabling Remove Unused CSS fixes the icons, exclude:

• Bootstrap Icons stylesheet
• bi- classes
• SoftwareRoad Knowledge Base pages

Use the exclusion method provided by your optimisation plugin.

Combined CSS files

Combining stylesheets may change the order in which icon styles load.

It can also fail when external stylesheets are handled incorrectly.

Test with CSS combination disabled.

If the icons return, exclude the Bootstrap Icons stylesheet from combination.

Delayed stylesheet loading

If external CSS is delayed until after page interaction, icons may appear late or remain blank.

Check whether the performance plugin delays:

• External stylesheets
• Font stylesheets
• Non-critical CSS

The Bootstrap Icons stylesheet should load early enough for icons to appear when the page is displayed.

Check font file requests

Bootstrap Icons normally uses a font file.

The stylesheet may load successfully while the font request fails.

In the browser Network tab, filter by:

• Font
• WOFF
• WOFF2

Look for failed requests linked to Bootstrap Icons or jsDelivr.

A blocked font request can leave empty spaces where icons should appear.

Font Content Security Policy

A Content Security Policy may allow the stylesheet but block the font.

For example:

• style-src allows jsDelivr
• font-src does not allow jsDelivr

In that case, the stylesheet request succeeds but the icons still fail.

Check both stylesheet and font errors in the browser console.

Mixed content errors

If the WordPress website uses HTTPS, the icon files should also load through HTTPS.

A mixed content error can occur if an external resource is requested through HTTP.

Check the browser console for mixed content warnings.

Also confirm:

Settings > General

uses HTTPS for both:

• WordPress Address
• Site Address

Check the active theme

A WordPress theme may apply CSS that hides icon elements.

Possible rules include:

• display: none
• font-family overrides
• font-style overrides
• font-size: 0
• opacity: 0
• overflow: hidden
• Generic rules targeting i elements

Inspect the missing icon and review the computed CSS styles.

Generic theme icon rules

Some themes use their own icon library and apply broad styles to every icon element.

For example, a theme may override all elements with classes beginning with bi.

This can prevent Bootstrap Icons from using their required font family.

Test with a standard WordPress theme on a staging website.

If the icons work there, the original theme contains a CSS conflict.

Check custom CSS

Search custom CSS for rules targeting:

• .bi
• Classes beginning with .bi-
• i
• Pseudo-elements
• Knowledge base cards
• Article icons
• Category icons

A custom rule written for another part of the website may accidentally affect SoftwareRoad Knowledge Base.

Temporarily disable the suspected CSS and reload the page.

Font family is being overridden

Bootstrap Icons need their own icon font family.

If another style forces a different font family onto the icon element or pseudo-element, the icon may appear as an empty square or not appear at all.

Use browser developer tools to check the computed font-family.

The Bootstrap Icons style should be allowed to apply.

Icons appear as empty squares

Empty squares or missing-character boxes usually mean:

• The icon font failed to load
• The wrong font family is applied
• The icon class is unavailable
• The stylesheet and font versions do not match
• A firewall blocked the font file

Check the font request in the browser Network tab.

Icons appear as strange letters

This can also indicate that the Bootstrap icon font is not being used.

Another font may be rendering the icon character code as normal text.

Check CSS conflicts involving:

• font-family
• font-style
• font-weight
• Pseudo-elements

Icons appear only after refreshing

This may be caused by:

• Delayed CSS loading
• Optimisation
• Race conditions
• CDN timing
• Browser cache
• Critical CSS omitting the icon stylesheet

Disable delayed or asynchronous CSS loading as a test.

The icon stylesheet should be available during the initial page render.

Icons work while signed in but not signed out

This often points to different caching or optimisation rules for public visitors.

WordPress administrators may receive an uncached page, while signed-out visitors receive:

• Cached HTML
• Combined CSS
• Removed unused CSS
• CDN-optimised files

Clear the public cache and test in a private browser window.

Icons work while signed out but not in the editor

The WordPress editor may not load the same Bootstrap Icons stylesheet as the public website.

The important check is the public knowledge base page.

A saved icon field can still work publicly even when no editor preview appears.

Icons work on desktop but not mobile

Check for:

• Mobile-specific CSS
• Separate mobile cache
• Different optimisation settings
• Responsive visibility rules
• Mobile browser privacy protection
• In-app browser blocking

Inspect the page on a real mobile device and in a narrow desktop browser window.

Icons work on one page but not another

Compare the two pages.

Check:

• Whether a custom image is saved
• The icon class
• Page cache
• Theme template
• CSS optimisation
• Whether that layout supports icons
• Whether the affected section is enabled

The issue may be limited to the individual item rather than the CDN.

Icons disappeared after a plugin update

After updating SoftwareRoad Knowledge Base:

1. Clear all WordPress caches.
2. Clear optimisation-generated CSS.
3. Clear the website CDN cache.
4. Reload the page privately.
5. Check the browser console and Network tab.

An older combined stylesheet may still be cached.

Icons disappeared after changing the theme

The new theme may:

• Override icon font styles
• Block external fonts
• Apply a new Content Security Policy
• Change CSS optimisation
• Hide icon containers

Test with browser developer tools and inspect the computed icon styles.

Icons disappeared after enabling a security plugin

Review:

• Content Security Policy headers
• External resource blocking
• CDN restrictions
• Firewall events
• Privacy headers
• Referrer rules

Temporarily test the specific restriction rather than deactivating all security permanently.

Icons disappeared after enabling performance optimisation

Clear all generated CSS files first.

Then test these settings individually:

• Remove unused CSS
• Combine CSS
• Delay CSS
• Minify CSS
• Critical CSS
• External file optimisation

Exclude the Bootstrap Icons stylesheet once the conflicting feature has been identified.

Check plugin and theme conflicts

Use a staging website for a full conflict test.

1. Keep SoftwareRoad Knowledge Base active.
2. Switch to a standard WordPress theme.
3. Deactivate other plugins.
4. Clear all caches.
5. Test a simple icon such as bi-book.
6. Reactivate plugins one at a time.
7. Restore the normal theme last.

The change made immediately before the icons disappear is the likely conflict.

Do not edit plugin files directly

Avoid changing SoftwareRoad Knowledge Base files to hard-code icon styles.

Plugin updates may overwrite those changes.

Use:

• Built-in icon fields
• Design settings
• Custom uploaded images
• Theme child CSS
• Proper CDN or CSP configuration

Keep a record of any custom CSS added.

Reinstall the plugin files

If the plugin files are incomplete or damaged:

1. Create a full WordPress backup.
2. Download a clean copy of SoftwareRoad Knowledge Base.
3. Replace or reinstall the plugin files.
4. Activate the plugin.
5. Check the licence.
6. Clear all caches.
7. Test a simple Bootstrap icon.

Do not uninstall saved content unless you understand what the uninstall process removes.

A practical Bootstrap Icon test

Use this process to find where the problem is occurring:

1. Confirm the SoftwareRoad Knowledge Base licence is active.
2. Edit one category.
3. Remove any custom category image.
4. Enter:

bi-book

5. Update the category.
6. Clear the knowledge base homepage cache.
7. Open the page in a private browser window.
8. Inspect the category card.
9. Check whether the bi-book element exists.
10. Check the Network tab for the Bootstrap Icons stylesheet.
11. Check the Network tab for the icon font file.
12. Review Console errors.

This separates saved setting problems from CDN or CSS problems.

Contact your hosting provider

Contact the hosting provider if:

• jsDelivr requests are blocked server-side
• The Content Security Policy is controlled by hosting
• Font files are blocked
• Server security rules reject external stylesheets
• A managed optimisation service removes the icon CSS
• The issue began after a hosting migration

Provide the failed resource address or browser error message.

Do not send your SoftwareRoad product key.

Contact SoftwareRoad support

Contact support if:

• A valid icon such as bi-book is saved
• No custom image is selected
• The page contains the icon element
• The Bootstrap Icons stylesheet and font both load successfully
• Cache and optimisation have been cleared
• The icon still does not appear

Include:

• Website address
• Affected page URL
• Icon class used
• Whether all icons or only one are missing
• SoftwareRoad Knowledge Base version
• WordPress version
• Active theme
• Caching and optimisation plugins
• Browser Console errors
• Network status for the stylesheet and font
• Screenshot of the affected area

Do not publicly share your full licence key.

Bootstrap Icons troubleshooting checklist

Before contacting support, check that:

• The icon class begins with bi-
• Only the individual icon class is entered
• The class is spelled correctly
• No accidental spaces are present
• A simple class such as bi-book has been tested
• The item was saved or updated
• No custom uploaded image is taking priority
• Icon size is large enough to see
• Icon colour contrasts with the background
• The layout supports icons in that location
• The Bootstrap Icons stylesheet loads from jsDelivr
• The Bootstrap Icons font file loads successfully
• Browser Console errors have been checked
• Content Security Policy allows the required style and font resources
• Hosting and network firewalls are not blocking jsDelivr
• Ad-blocking and privacy extensions have been tested
• WordPress, server and CDN caches have been cleared
• Remove Unused CSS and CSS combination have been tested
• Theme and custom CSS font overrides have been checked
• Plugin and theme conflicts have been tested on staging
• An uploaded custom image has been considered as an alternative

Bootstrap Icons should appear once the correct bi- class is saved and the visitor’s browser can load the required Bootstrap Icons stylesheet and font files from the CDN.