Custom app bar icon in Windows Phone 8.1 JavaScript apps

Today I had to add a custom icon to the app bar in a Windows Phone 8.1 HTML / JavaScript app and as it wasn't totally obvious how to do it and I had to dig around a bit, I thought I'd document and share my findings :)

The Search

Looking around for info on this, I struggled a bit, I think the Microsoft documentation on building Windows Phone apps with HTML, CSS and JavaScript is a bit lacking at this point in time and I often found search results ending up on pages about the Silverlight (C# and XAML) documentation. However eventually, I found this this page about Adding app bars (HTML) which was quite helpful, but unfortunately didn't cover how to add a custom icon.

After some more searching on the web I found a MSDN code sample: HTML AppBar control sample which covered this among other things.

The Solution

As so often, the solution was so simple that I should have guessed it!

Instead of using the standard format, where you're pointing to a named resource like so:
<button data-win-control="WinJS.UI.AppBarCommand" data-win-options=" {id:'cmdGoToStats', icon:'iconName', label:'stats'}"></button>

You just add the icon to your solution/project and point to it's location, like so:
<button data-win-control="WinJS.UI.AppBarCommand" data-win-options=" {id:'cmdGoToStats', icon:'url(icons/appbar.graph.line.png)', label:'stats'}"></button>

And then magic happens

One thing thing that threw me a bit and I've still not figured out yet, is how the app switches colour of the icon when the user changes betwen Dark or Light themes.
At first, before I found the sample, I tried adding seperate folders with dark and light icons etc.

However, following the solution above, I only added a white icon, meant for a dark background and when I switch the phone to a light background, the colour of the icon "automagically" switches to a dark colour!
Not sure what the deal is there but hopefully it's not something that will stop working all of the sudden (as magic sometimes has a tendency to do).

The Icons

As a tip, when it comes to Windows 8 and Windows Phone apps, if you've not come across it before, check out Modern UI Icons for your icon needs, they have a great collections and they're free!