Applies to: Office 365

I was reading through the issue list on the sp-dev-column-formatting repository and came across a question from Marc Anderson about using icons from external sources – specifically Font Awesome.

The good news is this is totally possible! In fact, I’ve just submitted a sample that addresses Marc’s use case of having a color-coded, custom icon display for a Gender column using Font Awesome icons:

The bad news is this isn’t nearly as simple as just specifying the iconName attribute like you do with UI Fabric Icons (but it isn’t that hard either).

The basic idea

One of the awesome things about column formatting is the ability to use an inline SVG element as one of the elmType values. Inside you can add a path element and specify the d attribute.

However, one of the not so awesome things about column formatting is that that is currently about as fancy as you can get with SVGs. The biggest hurdle in this case is the lack of a viewbox attribute. So we’ll have to adjust our icon SVG to not rely on the viewbox for proper scaling and then extract the d attribute for use in our format.

It’s really not as scary as that might have sounded.

Once we have the path instructions for our icon(s) we can use them like any other value with conditional operators and more. In fact, we can even dynamically build those paths if we want to get crazy about it (In fact, this is exactly how the Donut wizard in Column Formatter works).

Get the SVG for an icon

Many icon providers will allow you to download the SVG version of an icon. Both Material icons and Font Awesome allow this and there are many more. You can even mix and match since you aren’t bringing in a dependency on the actual fonts, you’re just using the SVG for individual icons.

For this post, we’ll be using Font Awesome. Here’s how to get an SVG for one of their icons:

1. From the Font Awesome site, find the icon you want to use in your format and click on it
2. Click the Download SVG button:
   
3. If you haven’t paid for a pro license, you’ll be prompted with an attribution notice. Click Agree & Download the SVG and the file will either open in the browser (in which case, right-click and save) or download directly

Unlike traditional images, you won’t actually upload this file anywhere and you won’t be using it in the src tag of an img element. Instead, we’ll be pulling the instructions directly out of the file (which is actually an XML file).

Format & extract path

Unfortunately, Font Awesome icons rely on a viewbox attribute (like they should) and so they won’t scale properly without some manipulation since we can’t specify the viewbox. We’ll use a free, open-source tool to do this called Inkscape:

1. Open the icon SVG in Inkscape
2. We’ll adjust the page size to have the path coordinates drawing at a 1:1 scale instead of relying on the viewbox translation. So choose File > Document Properties to open the Document Properties dialog
3. Under Custom Size, set the Width and Height both to 13px (or whatever size you are wanting, this is just the default size of icons in column formatting). The Viewbox should also have the same width and height:
   
4. Close the Document Properties dialog
5. That tiny square under your icon is the actual document, so let’s scale down our object to fit. Select the icon object.
6. In the toolbar, click the lock next to the W (width) property to lock the icon’s ratio:
   
7. Set either the W or the H property (whichever is bigger) to 13
8. Set both X and Y to 0
9. You’ll probably want to zoom in now
10. If it is square, skip to step 12. Otherwise, you’ll want to align the icon either horizontally or vertically as needed. You can do this using the Align and Distribute dialog. Choose Object > Align and Distribute
11. In the Relative To dropdown select Page then click the Center on vertical axis button if your icon is tall (Y>W) or Center on horizontal axis button if your icon is fat (W>Y):
    
12. Save your SVG
13. Open the SVG file in a text editor like VS Code
14. Scroll down to the only path element (near the bottom) and copy everything in the d attribute:
    

Using the path in a format

Instead of a span with an iconName attribute, you’ll use an svg with a path and a d attribute. A quick example should help clear that up.

Here is a simple format that shows an icon along with the current field’s value. A span with an iconName attribute is used (along with some padding and color) for the icon and then another span to show the field’s text (gist here):

Here’s what that looks like using the fly icon from Font Awesome (gist here):

Here’s what’s different:

• The icon span has been replaced with an svg element
• We have to specify the height and width since SVG’s have a large default size
• Instead of the color style attribute, we use fill
• We add a child element of path and set it’s d attribute to a complicated value (pulled from the icon’s SVG file) instead of a simple icon name

So… not as easy, but this opens up tons of options!

Fortunately, conditionally selecting an icon stays relatively simple since column formatting always allows either an operation or a value. So, where you might have used a conditional statement for the iconName attribute, you can just do the same thing for the d attribute.

Here’s what that looks like in the generic-svgicon-format sample:

The icons shown here and included in the gist code were adapted from Font Awesome which is available under the Creative Commons Attribution 4.0 International license.