The Hitchhiker’s Guide to Custom Fonts for SharePoint Developers

In the ever-expanding universe of SharePoint, Microsoft’s latest Brand Centre lets you add custom fonts everywhere. It’s crucial for SharePoint Framework developers to understand a few things.

Where Are My Fonts Located?

Fonts live on a small, slightly obscure planet known as “Brand Guide”, housed in a private document library called “Fonts”. From there, they are launched into the galaxy aboard a spaceship named SharePoint Public CDN.

Whenever a font lands in this document library and is used in a font package, it’s sent on a cosmic journey via the CDN again, so don’t worry—your fonts are always on the move.

Yes, But Where Are My Fonts Located in the Code?

SharePoint developers, being the curious creatures they are, often venture into the network tab of developer tools to locate the fonts. Indeed, there they are—floating in from the public CDN.

But you won’t find traditional CSS to load these fonts. Instead, the CSS Font Loading API does all the heavy lifting. You can learn more about it here.

Can I Use All Fonts and Variants Uploaded?

Short answer: No. Long answer: It’s complicated. Only fonts used by the Font Package are loaded on the page.

For example, if your package includes a font called “Babel Fish”, with weights like light, normal, and bold, only those specific weights get loaded.

Italic versions, however, do not tag along unless they’re specifically included.

In this whimsical scenario, the italic style may mimic the normal version, causing strange and slightly unsettling font behavior—something that dedicated font designers would grimace at. Rendering the wrong font style may upset your users.

CSS Custom Properties for Fonts

Various CSS custom properties are available for font usage, based on the Fluent Design 2 typography system.

While these definitions work well in a design system, third-party developers might find it tricky to ensure consistency across web parts and font combinations.

Set Up the Correct Font for Your Web Part

To access these font properties, use this simple CSS format:

.myWebPart{
    font-family: var(--fontFamilyCustomFont100, --fontFamilyBase);
}

There are custom font slots ranging from 100 to 1600, which you can explore in the Fluent UI React v9 docs.

Font Weights in SharePoint

Here’s a snapshot of available font weights:

For missing weights, the browser chooses the closest available value. For instance, font-weight 500 will handle anything below 500, while 600 covers everything above.

The Perks of Times New Roman (And How to Avoid It)

Every so often, when JavaScript in SharePoint doesn’t quite finish its job, you might be greeted by an unexpected guest—Times New Roman, the browser’s loyal fallback font. While it’s a classic, it might not fit the modern look you’re going for. Thankfully, there’s a straightforward way to avoid this entirely.

Microsoft could have solved this with a little trick well-known among web developers: defining a default font at the body or root level of your HTML document. By doing this, even if JavaScript decides to take a break, your chosen font will still show up where it belongs.

Since fonts inherit their properties from parent elements, setting the primary font on the root element of your web part ensures that all its descendants follow suit. Here’s a simple example of how to keep things consistent:

.myRootClass {
    font-family: var(--fontFamilyCustomFont100, --fontFamilyBase);
}

.myRootClass > anotherSubClass {
    // I automatically inherit the same font as my parent!
}

With this setup, you can ensure that all your web parts use the right font, avoiding any unexpected defaults. And if you need to switch fonts for specific sections, you can easily do so without affecting the rest of your layout.

So, while Times New Roman may make an occasional appearance, it’s entirely within your power to keep it in the past, ensuring your SharePoint site stays as stylish and modern as you’d like.

How Do I Get Fonts Programmatically?

To explore fonts programmatically on a SharePoint page, run the following TypeScript code:

const fonts = await document.fonts as FontFaceSet;

const promises: FontFace[] = [];

fonts.forEach(font => promises.push(font));

const fontData = await Promise.all(promises);

for (let i = 0; i < fontData.length; i++) {
  console.debug(fontData[i]);
}

It shows all registered fonts along with weights and styles in the console.

In comparison all custom fonts uploaded to the brand center registered on the page.

Are Variable Fonts Supported?

Ah, Variable Fonts. A marvel of modern typography that, like the improbability drive, allows a font file to do what once seemed impossible. With variable fonts, a single file can carry the weight (literally) of multiple styles—stretching, shrinking, and slanting itself at will, as if your web page had finally discovered yoga. The promise? Faster loading times, fewer font files cluttering the internet, and more flexibility than a Vogon bureaucrat trying to read poetry while filing paperwork.

If you’re keen to tinker with this wonder, you can try them out on v-fonts.com or Google Fonts, assuming you have a few light-years to spare.

Now, instead of your browser needing to fetch separate files for each style and weight—an act as tedious as trying to navigate hyperspace by feel—it can simply download two files. Like this:

@font-face {
  font-family: 'BabelFish';
  src: url('babel-fish-variable.woff2') format('woff2');
  font-weight: 100 900; /* Handles everything from a whisper to a shout */
  font-stretch: 75% 100%; /* Can stretch itself to look wider, but never bloated */
  font-style: normal; /* The well-behaved, 'I’ll be normal' style */
}

@font-face {
  font-family: 'BabelFish';
  src: url('babel-fish-variable-italic.woff2') format('woff2');
  font-weight: 100 900; /* Again, a range as wide as a hyperspace bypass */
  font-stretch: 75% 100%; /* Stretchy, but this time with a rakish slant */
  font-style: italic; /* For when your text is feeling just a little *fancy* */
}

This delightful pairing means you’ve got one file for normal, and another for italic, each supporting a full range of weights, from delicate Hairline to robust Ultra. It’s the kind of flexibility that would make even Zaphod Beeblebrox’s heads spin.

Of course, your fonts will also be compressed using modern techniques like Brotli Compression (which sounds like something you’d sprinkle on a salad) or Glyph Consolidation, because, apparently, we’ve reached the point where even fonts need to be optimized for galactic travel.

And for the truly adventurous, here’s how to load them using the mysterious power of JavaScript:

// Load the sensible, down-to-earth normal style
const normalFont = new FontFace('BabelFish', 'url(babel-fish-variable.woff2)', {
  weight: '100 900',
  stretch: '75% 100%',
  style: 'normal'
});

// Load the italic, stylish font for when you're feeling extra cosmic
const italicFont = new FontFace('BabelFish', 'url(babel-fish-variable-italic.woff2)', {
  weight: '100 900',
  stretch: '75% 100%',
  style: 'italic'
});

// Add them to the document, just like tea to the universe
Promise.all([normalFont.load(), italicFont.load()]).then(function(fonts) {
  fonts.forEach(function(font) {
    document.fonts.add(font);
  });
  console.log('Variable fonts loaded—slightly less impressive than hyperspace, but still neat.');
});

Yet, alas, SharePoint—much like Arthur Dent stranded on prehistoric Earth—has chosen to ignore the full potential of these fonts. It registers only the normal weight and style for now, as if it’s saying, “No need to get fancy, we’ll stick with plain old normal, thank you very much.” In the grand universe of typography, this is a bit like having a spaceship that can travel at light speed but only using it to fetch groceries.

So, while variable fonts are becoming increasingly common—Microsoft’s own Segoe UI Variable now proudly serving as the default in Windows 11—SharePoint has yet to fully embrace their brilliance. One can only hope that, in time, it will rise to the occasion and stop treating fonts as though they’re stuck on Earth with a broken digital watch.

In conclusion: yes, you can use variable fonts in SharePoint. Just don’t expect to enjoy their full, glorious range—yet.

Can I Register Fonts Myself?

Yes! The fonts in your document library are uploaded to the CDN automatically. Variable fonts can be registered using their CDN URL:

https://publiccdn.sharepointonline.com/<tenant name>/sites/BrandGuide/Fonts/<font file name/>

This allows full customisation, though developers may face limitations working with Fluent Design’s built-in constraints.

A computer interface (API) to detect all uploaded fonts for font bundle on a site would be great, but yet not in sight. It might be the next task for Deep Thought after answering the ultimate question of life, the universe, and everything. (In seriousness an API would be highly appreciated)

And Thanks for the Fish

While this guide isn’t exhaustive, it should offer a cosmic overview of custom fonts in SharePoint development. Let me know if any gaps need filling, and happy coding!

Also please checkout Vesa Juvonen’s video on using SharePoint Brand center font settings in custom SPFx solution.

PS: As many might have guessed, I used everyone’s new favourite tool, Chat Generative Pre-Trained Transformers, to write this blog post. In all seriousness, I wanted to give a bit of a humorous look at the dry topic of typography and how SharePoint handles it. I love the work of Douglas Adams. Next time, it will be all mine again.
It’s been a while ago I wrote on custom fonts in SPFx.