Leverage SharePoint Brand Center Font in SharePoint Framework

In the “Hitchhiker’s Guide to Custom Fontst for SharePoint Developers”, I already explained in a humorous but serious way how the custom font work.

The official Microsoft documentation is somewhat incomplete. Andrew Connell’s article on this topic shows a simple scenario for custom font.

Let me show you what is missing from the documentation so you can get a full overview of that topic.

How to use the documentation

Microsoft lists the following table at the bottom of their documentation.

While you get some idea of how the custom slots are applied, this section focuses on the font or, more precisely, the ‘font-family’ property. The compiled list is a mashup of three other sources.

One source can be found in the Fluent 2 Typography documentation.

You will find the name related to the SharePoint Framework documentation here.

The second source is the classic Fluent UI Rect 8.x documentation.

This documentation lists only the font sizes and font weights.

Last but not least, the third source, which shows the font definitions in more detail, is the Fluent UI 9 documentation.

Confused? Don’t worry—I’ve got you covered, and there is an easier way to move forward.

Practical Usage of font

CSS has various properties that are mostly the same, which can sometimes make it confusing. To define a font, you have multiple properties you can use and need to use.

The common ones are font-family, font-weight and font-style.

Let’s focus on the first custom font slot – CustomFont100 is used for ‘Caption small’. This directly translates to the first entry of the Fluent UI React entry.

From here, we get more information on font size, weight, and line height. Let’s compile this into a CSS class that we can use.

.caption1{
    font-family: var(--fontFamilyCustomFont100);
    font-size: var(--fontSizeBase100); // 10px
    font-weight: var(--fontWeightRegular); // 400
    line-height: var(--lineHeightBase100); // 14px
}

These are the official slots that Fluent UI uses. With all those variables, you get the same style as the caption1 with your custom font.

If you like using these custom fonts like Microsoft, use them in their product. This is the way forward.

The only thing left is compiling it down to all the 17 “custom font” slots; we are ready to leverage the custom fonts.

One-time include for the win

Instead, we can do something smarter using these four properties, such as the font shorthand property.

.caption1{
    font: <font-weight> <font-size>/<line-height> <font-family>
}

So the only thing we need to define again is the font weight followed by font size, line height and font family.

In our special case, this looks like this:

.caption1{
    font: var(--fontWeightRegular) var(--fontSizeBase100)/var(--lineHeightBase100) var(--fontFamilyCustomFont100);
}

This gives us exactly how the “customFont100” slot should have been defined.

There is something more. Instead of using this directly on the font property, we can use the value in a Custom CSS property.

On a web part, we need to inject the following.

.myWebPartRoot{
    // Define a variable for the first slot
    --customFontDefinition100: var(--fontWeightRegular) var(--fontSizeBase100)/var(--lineHeightBase100) var(--fontFamilyCustomFont100);

    // use the slot
    font: var(--custom100);
}

The first is our property definition --customFontDefinition100 property, which combines all the required values to render the font properly.

Later, we can use the—custom100 font wherever it is needed. It will be applied to the whole web part because it will be inherited from the highest point in the DOM tree.

Well, but there are still 17 slots to define.

The complete definition for usage of custom fonts

Suppose you would like to create this list now yourself. I have you covered here as well. The following CSS contains all 17 slots, which follow the definition of Fluent UI 9.

.myWebPartRoot{
/* Custom Font Properties */
:root {
  /* Caption 2 - Caption small */
  --customFont100: var(--fontWeightCustomFont100, var(--fontWeightRegular)) var(--fontSizeBase100)/var(--lineHeightBase100) var(--fontFamilyCustomFont100), var(--fontFamilyBase);

  /* Caption 2 Strong - Caption medium */
  --customFont200: var(--fontWeightCustomFont200, var(--fontWeightSemibold)) var(--fontSizeBase100)/var(--lineHeightBase100) var(--fontFamilyCustomFont200), var(--fontFamilyBase);

  /* Caption 1 - Caption large */
  --customFont300: var(--fontWeightCustomFont300, var(--fontWeightRegular)) var(--fontSizeBase200)/var(--lineHeightBase200) var(--fontFamilyCustomFont300), var(--fontFamilyBase);

  /* Caption 1 Strong - Label small */
  --customFont400: var(--fontWeightCustomFont400, var(--fontWeightSemibold)) var(--fontSizeBase200)/var(--lineHeightBase200) var(--fontFamilyCustomFont400), var(--fontFamilyBase);

  /* Caption 1 Stronger - Label medium */
  --customFont500: var(--fontWeightCustomFont500, var(--fontWeightBold)) var(--fontSizeBase200)/var(--lineHeightBase200) var(--fontFamilyCustomFont500), var(--fontFamilyBase);

  /* Body 1 - Label large */
  --customFont600: var(--fontWeightCustomFont600, var(--fontWeightRegular)) var(--fontSizeBase300)/var(--lineHeightBase300) var(--fontFamilyCustomFont600), var(--fontFamilyBase);

  /* Body 1 Strong - Paragraph small */
  --customFont700: var(--fontWeightCustomFont700, var(--fontWeightSemibold)) var(--fontSizeBase300)/var(--lineHeightBase300) var(--fontFamilyCustomFont700), var(--fontFamilyBase);

  /* Body 1 Stronger - Paragraph medium */
  --customFont800: var(--fontWeightCustomFont800, var(--fontWeightBold)) var(--fontSizeBase300)/var(--lineHeightBase300) var(--fontFamilyCustomFont800), var(--fontFamilyBase);

  /* Body 2 - Paragraph large */
  --customFont900: var(--fontWeightCustomFont900, var(--fontWeightRegular)) var(--fontSizeBase400)/var(--lineHeightBase400) var(--fontFamilyCustomFont900), var(--fontFamilyBase);

  /* Subtitle 2 - Heading extra small */
  --customFont1000: var(--fontWeightCustomFont1000, var(--fontWeightSemibold)) var(--fontSizeBase400)/var(--lineHeightBase400) var(--fontFamilyCustomFont1000), var(--fontFamilyBase);

  /* Subtitle 2 Stronger - Heading small */
  --customFont1100: var(--fontWeightCustomFont1100, var(--fontWeightBold)) var(--fontSizeBase400)/var(--lineHeightBase400) var(--fontFamilyCustomFont1100), var(--fontFamilyBase);

  /* Subtitle 1 - Heading medium */
  --customFont1200: var(--fontWeightCustomFont1200, var(--fontWeightSemibold)) var(--fontSizeBase500)/var(--lineHeightBase500) var(--fontFamilyCustomFont1200), var(--fontFamilyBase);

  /* Title 3 - Heading large */
  --customFont1300: var(--fontWeightCustomFont1300, var(--fontWeightSemibold)) var(--fontSizeBase600)/var(--lineHeightBase600) var(--fontFamilyCustomFont1300), var(--fontFamilyBase);

  /* Title 2 - Heading extra large */
  --customFont1400: var(--fontWeightCustomFont1400, var(--fontWeightSemibold)) var(--fontSizeHero700)/var(--lineHeightHero700) var(--fontFamilyCustomFont1400), var(--fontFamilyBase);

  /* Title 1 - Title small */
  --customFont1500: var(--fontWeightCustomFont1500, var(--fontWeightSemibold)) var(--fontSizeHero800)/var(--lineHeightHero800) var(--fontFamilyCustomFont1500), var(--fontFamilyBase);

  /* Large Title - Title medium */
  --customFont1600: var(--fontWeightCustomFont1600, var(--fontWeightSemibold)) var(--fontSizeHero900)/var(--lineHeightHero900) var(--fontFamilyCustomFont1600), var(--fontFamilyBase);

  /* Display - Title large */
  --customFont1700: var(--fontWeightCustomFont1700, var(--fontWeightSemibold)) var(--fontSizeHero1000)/var(--lineHeightHero1000) var(--fontFamilyCustomFont1700), var(--fontFamilyBase);
}

Include this in your webpart. You have all the font slots available.

If you wonder why the fontFamilybase is in there, it gives you the standard Segoe UI font instead of SharePoint’s default font, Times New Roman.

It isn’t very easy

And this is how you leverage SharePoint Brand Center Font in SharePoint Framework. It took me a while to understand this, and it was not because glueing all the different pieces was tough. Would those CSS custom properties make it easier for first and third-party developers?

Definitely. Why make it easy when you can make it complicated instead? It doesn’t matter much when the only thing you use is Fluent UI, but it is a framework that only scratches the surface of a modern web design. Sooner or later, you need to build custom experiences.

Custom fonts in SharePoint have many limitations and quality issues in their implementation. For example, they use the JavaScript Font loading API instead of the performance-optimised CSS equivalent.

Even though this was just shipped, modern fonts are not properly supported—a fact we have needed, sadly, for years.