The Complete Guide to Icons and Mendix
How to map custom icons to the Mendix Glyphicon set.
This one goes out to Willem Gorrisse, lets see if we can get great icon support in Mendix before 2023!
Help Willem out by voting on this idea post.
24–5–22 edit: changed all “context-icn” to “icn-context”, to be slightly more futureproof
There seems to be some confusion about icons in Mendix. So with this blog, I hope we can create some best practices, that way if a front ender changes teams, they understand what has been done.
Blogtip
Mendix Studio Pro 9 will be referred to as MXSP9 from here on
Icons types.
Life would be so much easier if there was a single format for icons, but then again, variety is the spice of life. There are 4 main icons types, each with its own pros and cons (icons-fonts, CSS icons, SVGs, PNGs).
MX Best practise
The MX UX community has decided that icon-fonts are the best practice when implementing icons.
Click here to join the MX UX slack
Icon Fonts
Icons-fonts are characters that have been mapped to show a certain icon. This gives them the ability to be manipulated the same way as fonts can through CSS (such as changing the color based on brand colors or giving them hover states). Because they are a font, they also remain a vector and are crisp no matter the size.
Pros
The best practice within Mendix
Lots to choose from.
Easy to manipulate through CSS
Cons
The good ones are not free (but also not expensive).
Can be awkward to configure. (read how here)
Not rendered inside of MXSP9.
Icon packs
Glyphicon (MXSP9 default)
Font awesome
https://icomoon.io/
https://themify.me/themify-icons
https://zurb.com/playground/foundation-icon-fonts-3
Mendix
Font awesome appstore module
CSS icons.
CSS icons are probably the least known in this list and used to be my go-to icon type. The best example is css.gg icon pack. They worked well for me because the license model is friendly for consultants and because they are pure CSS, they are simple to load in and easy to change color and size.
The drawback is that there are not many to choose from, and if you are working in a niche field, it is sometimes difficult to find icons that fit the context.
These are no longer my fav due to the MX UX Community deciding that icon-fonts are the most common, easiest to use, and also have open-source versions.
Pros
Can change size/color with dynamic classes.
Easy to load in.
Can be easily remapped.
Cons
Limited choice
Icon Packs
css.gg
SVG icons
The main reason to use SVG’s is to display images that contain multiple colors such as illustrations, company logos, emojis, or stickers.
The tricky thing about SVG’s is that they can be loaded into a Mendix app in 3 different ways (SASS/CSS, in MXSP9 & inline).
SASS/CSS
The first and most common way for front-enders to implement is to load in icons through the SASS. This is great when you have things like company logos. They can easily be mapped to the “brand-logo” class when named correctly. This also allows you to easily change an icon in one location and it changes everywhere in your project.
In MXSP9
The second way to load them in is through MXSP9 as you would an image. The great thing about this is that you are able to see the icon in MXSP9 and this helps developers get an idea of what icons are in their Mendix pages. There are some security issues here, because SVG's may contain malicious scripts, so be warned.
Inline
The last is inline SVG. Inline SVG's can be loaded in through the HTML widget, and are sometimes hardcoded into widgets. This is the worst way to implement an SVG because it makes it difficult to manipulate, recolor, or replace the icon. Avoid this at all costs.
Pros
MultiColor.
Lightweight file size.
Renders nicely in different sizes.
Cons
Cant have hover states.
Cant be rebranded with SASS variables.
SVG’s can contain malicious scripts if downloaded from untrustworthy sources.
IconPacks
https://app.streamlinehq.com/illustrations
PNGs, JPGs, GIFs & Illustrations
Pixel formats have a long tradition of being the best way to implement an image on the web. If it comes to photos, this is still the way to go.
Icons are often less complex than photos, therefore are now usually created and loaded in as a vector format, so that they remain crisp at all sizes.
The nice thing about these icons is they can have multiple colors.
Loaded into Mendix, and can be rendered inside MXSP9.
Another cool thing is that if you use gifs, they can contain animations, which might give your user a bit of “delight”.
Pros
MultiColor.
Renderable in MXSP9.
Gifs can be animated
Cons
Can’t have hover states.
Can’t be rebranded with SASS variables.
Slightly larger file size.
Can look “pixely” when resized.
IconPacks
https://www.flaticon.com/
Context Icons vs Noun Icons.
In short;
an icon can be named to describe the action it communicates
or named after the image it represents.
Remove vs Trashcan.
Edit vs Pen.
SingleSelect vs Radio.
My personal preference is to use context naming conventions.
The reason for this is that this makes it easy to govern and maintain your icons.
An example of this could be; a change in your design system, and now all the trashcan icons must now become a cross icon.
Have fun finding all the trashcans in your applications.
If you had a context icon named “context-remove” in your CSS, you could remap whatever icon you want to this, and change it in a single spot.
This brings us to “icon mapping”.
Icon Mapping (finally, the good stuff)
What is Icon mapping?
In short, icon mapping is telling the browser that if it sees a certain class, it needs to show a certain icon.
This section is split into 2 parts:
- Context mapping
- Glyphicon remapping
Context Mapping
Context mapping is a methodology that can communicate context to the design system, and to the user.
Basic context states are already supported by the HTML, like hover/focus states, other states are default in Mendix (like the selected state in a list-view), and other forms of context are often too specific or abstract and must be set manually.
Dynamic classes are a great way to set context based on when specific conditions are met.
Usually, when done manually there will be a class called “context-X”, this way all developers know that certain elements will be changed due to the context that is given.
Context can also be given on different “levels”.
Top-level context affects itself and all the underlying elements, such as a card with the class .card.context-success.
Specific-context only affects itself, for instance, a container with the class .icn-context.context-chevron.
Let's look at an example
For a checklist we developed, we needed to communicate 3 states. Pending/accepted/declined.
There was no definitive visual design yet, but the wireframes were finalized, so we could start building.
For this example, we used a top-level context because we wanted to be able to change more than just the icon if needed.
.icn-context{
@extend .fa-xl;
@extend .far;
line-height: 1;
}
.context-default{
.icn-context{
@extend .fa-circle;
}
}
.context-success{
.icn-context{
@extend .fa-check;
color: $cl-semantic-success;
}
}
.context-danger{
.icn-context{
@extend .fa-xmark;
color: $cl-semantic-danger;
}
}During the development process, we decided to change the background color to match the state and swap out the clean icons for icons that have a circle around them. Because we used context methodology it was quite trivial to swap the icons with new ones and add background colors to the elements.
.icn-context{
@extend .fa-xl;
@extend .far;
line-height: 1;
}
.context-default{
.icn-context{
@extend .fa-circle;
}
}
.context-success{
.icn-context{
//@extend .fa-check;
@extend .fa-circle-check;
color: $cl-semantic-success;
}
}
.context-danger{
.icn-context{
//@extend .fa-xmark;
@extend .fa-circle-xmark;
color: $cl-semantic-danger;
}
}.card{
&.context-default{
// has default card background color
}
&.context-success{
background-color: $cl-bg-semantic-success;
}
&.context-danger{
background-color: $cl-bg-semantic-danger;
}
}
Protip
Context icons work extremely well when combined with dynamic classes.
But if there are multiple context icons this might not always work well.
Glyphicon mapping
For a complete list of all the glyphicons (mapped to css.gg but easily remapped), use this .scss file
If you want a Mendix module, with all the icons too, start bugging me on slack.
Mendix uses glyph icons in a lot of places, the opening, and closing of group boxes, or as icons in your navigation and links.
If you are using a custom icon pack, it is a good idea to start with remapping the Mendix glyph icons.
These icons are and will always be “Noun-Icons”, so make sure you have strict guidelines on when to use a trashcan or when to use a cross icon.
In order to remap the icons, we will need to load in your new icon set, and overrule the glyphicon with the new icon (depending on the icon set this may differ)
.glyphicon-ok {
@extend .fa-check !optional;
}It is also possible to do this for multiple icons using the @each function in sass.
See this file for all the glyphicons
$icons:
asterisk asterisk false,
plus math-plus true,
euro euro true,
minus math-minus true;@each $icon in $icons {
.glyphicon-#{nth($icon, 1)} {
@extend .fa-#{nth($icon, 2)} !optional;
@if #{nth($icon, 3)} == 'true'{
&:before{
content: none;
}
}
}
}
Drawbacks of remapping glyphicons?
Currently the only way to get a glyphicon into mendix (that is not in a default widget) is by creating a link, removing the text and selecting an icon. From a HTML perspective this is really bad practise. Another downside is that if you use an icon that has no glyphicon counterpart, FrontEnders will choose to sacrafice often unused icons (such as the ice-lolly) now you might have random ice-lolly icon in your Mendix app. Lastly Dynamic classes dont work very well with how Mendix implements glyphicons through the link button workaround.
Some last words of random advice.
Design properties
This blog is getting huge, but in short you can make design properties for your icon classes.
Read up on design properties here
Icon Organisers
If you work this much with icons, it's a good idea to have some kind of icon organizer.
With an icon organizer, you can import your icon set, search, recolor, export and drag and drop them straight into Figma, Powerpoint or most other application.
For Windows: Nucleo
For Mac: Iconjar
Icon sizing and the Pixel grid
“ My icons are vector, so they always look good” is a fallacy a lot of people tend to fall for.
Screens are made of pixels, if a line sits exactly on a pixel, it will look sharp. Icons tend to be created with a bounding box of a certain size (eg. 24*24px). When an icon is optimized for a specific size and its bounding box is displayed at this size, the pixels of the icon will line up exactly with the pixels of your screen creating a sharp rendered icon (if the icons are created correctly).
Idea forum
And lastly, some ideas for you to vote on to make icons management better in Mendix.
Icon Manager
https://forum.mendix.com/link/ideas/2060
Make it easy to add an icon to an input field
https://forum.mendix.com/link/ideas/2612
If you liked this blog, share it on LinkedIn, and tag me in it :D
My Linkedin
From the Publisher -
If you enjoyed this article you can find more like it on our Medium page. For great videos and live sessions, you can go to MxLive or our community Youtube page.
For the makers looking to get started, you can sign up for a free account, and get instant access to learning with our Academy.
Interested in getting more involved with our community? Join us in our Slack community channel.
