How to use custom fonts in a SharePoint Framework solution

Introduction

Do you need to specify a custom font in your SharePoint Framework solution? This blog post is for you.

SharePoint Online nowadays supports custom fonts through Brand Center, allowing organizations to enhance their branding by incorporating unique typography. However, in certain cases, it might be necessary to use a particular font that align with the company’s branding guidelines, and for some policies, it’s not allowed to load it from an external URL, which can pose a significant challenge.

Here I will cover how to bundle the custom font in your SPFx solution and how to use it inside your SCSS files.

You can find the sample I’ve created for writing this blog post here.

This sample uses webpack version 5 and SPFx version 1.20. If you’re on an older version of SPFx (before 1.19), you are almost likely using webpack version 4 and that requires some changes in the configuration of webpack. If you are in that situation, I suggest you to skip to the final section of this blog post and visit Stefan Bauer’s one.

Visual appearance

Starting with the visual appearance of the sample solution, and to give an idea of what we are talking about, here is the web part:

This is a really simple web part where you can find:

• a title, not styled with the custom font.
• a secondary title, styled with the custom font.

The two titles are styled differently to have a better differentiation between them.

Now that we know what we will accomplish let’s cover how to achieve this.

Show me the code

To use a custom font in your SPFx solution, first of all, you have to download the font file.

In this sample I’ve downloaded the Oxygen-regular font from here.

Once that we have the font file let’s see how to include it in the SPFx solution.

In this blog post I am using a TTF file, if you are using a different format you will have to update the code accordingly to your font file extension.

The solution has a default SPFx structure:

The only difference from a default structured solution is that, under the src folder, there’s a styles folder and inside of that, under the fonts folder, there’s the custom font file. This is not mandatory but I like to structure the solution in this fashion.

Once that we have our solution structured, we will need to instruct webpack to keep into account the custom font file. To achieve this, the first thing to do, is to configure webpack. Inside the gulpfile.js we will declare how to handle the font files and where to put those in the lib folder.

const fontLoaderConfig = {
  test: /\.(woff(2)?|ttf|eot|svg)(\?v=\d+\.\d+\.\d+)?$/,
  type: "asset/resource",
  dependency: { not: ["url"] },
};

This configure webpack (version 5) to load all the font files and place those in the lib/styles/fonts folder.

Now it’s needed to merge the configuration so that webpack will effectively use it:

build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfiguration) => {
    generatedConfiguration.module.rules.push(fontLoaderConfig);
    return generatedConfiguration;
  }
});

Next, a new SCSS file has to be created in order to allow loading the font in other SCSS files. As seen previously in the structure of the solution, in the styles folder, there’s a _fonts.scss file. This file declares a font face as follows:

@font-face {
  font-family: 'Oxygen';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: local('Oxygen Regular'), 
      local('Oxygen-Regular'),
      url(../../../styles/fonts/Oxygen-Regular.ttf) format('truetype');
} 

Now, to use the custom font in the web part, simply import the _fonts.scss file into the web part’s SCSS file:

@import '../../../styles/fonts';

And use the custom font where needed, for example in a content class:

.content {
  font-family: 'Oxygen';
}

Finally use the SCSS class into the needed element inside the web part component:

<h3 className={styles.content}>
  {strings.Content}
</h3>

Now the SPFx solution makes use of custom fonts!

Conclusions

Using custom fonts can be tricky but in the end it all comes at configuring webpack correctly and then use the fonts inside your SCSS files. In this example I’ve used webpack version 5, in case you’re on an older version you can reference Stefan Bauer’s blog post here for a different way of configuring webpack.

Hope this helps!