Issue: I cannot get icons to display on the website using umbraco 17.
I think I am missing something basic. A step people more familiar with the cms know to do but just isnt clearly documented in the places that I have looked.
I am using:
Visual Studio 2026
I have also attempted to simply run things using powershell using dotnet commands.
Umbraco cms version 17.7 which shows as the latest.
I created it by following the instructions found here:
dotnet new install [email protected]
dotnet new sln --name Umbraco17Test
dotnet new umbraco --name Umbraco17Test
dotnet sln add Umbraco17Test
cd {path to my project}
dotnet run
included packages:
Microsoft.ICU.ICU4C.Runtime (72.1.0.3)
Umbraco.Cms (17.7.0)
Umbraco.Cms.DevelopmentMode.Backoffice (17.7.0)
Umbraco.Community.Contentment (6.3.1)
The new project template created it with the first three. Contentment is something that I added as an attempt to get icons working. it is also used by the existing site I am trying to upgrade.
The basic issue:
<umb-icon name="icon-umbraco" color="blue"></umb-icon>
I am attempting to use the umb-icon code in a template to display the umbraco icon and this simply leaves that section of the page white. Unfortunately, the instructions on how to use icons are sparse.
My understanding based on how this is written is that there is a limited number of built in icons. which can be found here storybook - Storybook and if i want to add additional icons beyond that i need to follow the extension. I am not currently worrying about extending additional icons. the ones there by default should be good enough for my needs (unless the requirements change in the future)
In an attempt to solve this, I followed the instructions straight from the beginning located at:
when i got to the section for “Creating your first template” i added in the icon instructions from the other page into this page. I of course do all the necessary saving and publishing and refreshing.
When visit the page there is no image. I can view source on the page and see this html so I know it was successfully added to the template.
Is there something here that I am missing to get this icon to display? another package that needs to be installed? specific javascript or css that needs to be added to the page? Again, these are the built in icons and i do not see any instructions on that needed to be included anywhere I have looked.
A team member has also attempted similar steps using the latest version of 18 and is seeing the same issue.
Explanation:
So the issue I described above is my attempt to simplify the issue down to its most basic. What I am actually doing is upgrading an existing Umbraco site from 13 to 17. This has, of course, run into multiple issues, but I think i have solved all of them except the icon issue.
This website was originally build for my company by a consultant a while back. It has been minorly modified by the development team a couple of times since then, but by nature of it being a CMS, i.t. has mostly left it alone so the business can have the site look however they want without involving us.
Now dotnet 8 is going out of support, and umbraco 13 with it and this needs to be upgraded. as 17 is the LTS thats the version we are going with. I did run across a number of issues that I was able to find the instruction on how to solve, either on umbracos site or just genral knowledge forums, but the one that I cannot solve is Icons. I am aware that 14 changed how icons work. It seems to have remove IIconService from the Cms. and any attempt I make to continue use icons seems to fail. As this post implies, I have not used Umbraco prior to this project so I am not familiar with any of its pecularities, nor is anyone else on my team.
The existing site is making use of a community extension named contentment which comes with an Icon picker. The existing templates used the IIconService GetIcon method to retrieve the svg to display icons. IIconService is no longer available. And I have been trying to get ANY icon solution to work since. This included following the steps I stated above and creating a fresh site that was not subject to being upgraded or containing old code/migration issues that potentially could be causing issues. But even that is not displaying any icons.
and just like when I had a fresh new site, adding the umb-icon html tags to any existing page has not shown any image.
I can only conclude that there is something that I am missing that is required to get any of this to work.
While the current website uses contentment, I have no qualms about removing is and using a different Icon solution. If there is an icon picker type thing build directly into the cms I would be happy to use that. I did try another IconPicker community tool but that failed as well.
Additional Notes:
The app_plugins folder was never automatically added by any of these processes. I have tried manually creating that folder under wwwroot as well as at the root of the project and neither have had any files added to them at runtime. the version 13 website copied things into that folder upon run of the app. I do not know if that is a difference in versions of umbraco or if that is a bug. and google searching for that issue only shows older discussions on older umbraco versions. this leads me to believe that perhaps that is no longer being used and this is not an issue, but the documentation for making extensions seems to indicate that they at least should go in here still and even they are not.
As my whole reason for doing this is because dotnet 8 is going out of support, that does also mean that I am switching from Visual Studio 2022 to visual studio 2026 as 2022 does not run dotnet 10.
I did notice that inside backoffice exists the ability to select icons for document types. and those do display inside of backoffice. reusing that icon picker to select icons to display on the website is perfectly acceptable.