Using custom fonts in your theme

Custom fonts are CSS files hosted on a server that define font styles. In Experience Builder, you can add custom fonts to your theme in two ways.

Method 1: using Google Fonts

Step 1: Choose a font

Go to the Google fonts website:

• Browse or search for the font you want (for example, “Noto Serif” or “Roboto”).
• Click the font card to open its details page.

Step 2: Select font styles

On the font details page, preview the available styles. Once you've decided, click Get font in the top-right corner, then click Get embed code to open the configuration page.

On this page:

• Select the font weights and styles you need (e.g., Bold, Italic).
• Click + Select this style to add them.

Step 3: Copy the CSS link

Once you finish selecting styles, a <link> tag will appear on the right, like this:

1
<link href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">

✅ Only copy the URL inside the href attribute:

1
https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap

Step 4: Add the URL to your theme

Open the variables.json file in your theme folder and add the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "ref": {
    "typeface": {
      "customFonts": [
        {
          "name": "Roboto",
          "url": "https://fonts.googleapis.com/css2?family=Roboto&display=swap"
        }
      ],
      "fontFamily": "Roboto"  // Set Roboto as the base font for the theme
    }
  }
}

Step 5: Apply the font

In your terminal, navigate to the client directory and run:

1
npm start

Then open Experience Builder. If everything is set up correctly, your app will now use the Roboto font. You can also verify it by going to the Theme Settings page, under Typography, where Roboto should appear in the font selector.

Method 2: using local fonts

Step 1: Add local font files

Place your font files under the your-theme/assets/fonts directory. In this example, we'll use the font Lato.

Step 2: Reference the font files

In your style.scss or style.ts file, define the font family by using the @font-face rule to load the font files:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// style.scss
/* Lato Regular */
@font-face {
  font-family: 'Lato';
  src: url('./assets/fonts/Lato/Lato-Regular.ttf') format('truetype');
  font-weight: 400;
  font-style: normal;
}

/* Lato Italic */
@font-face {
  font-family: 'Lato';
  src: url('./assets/fonts/Lato/Lato-Italic.ttf') format('truetype');
  font-weight: 400;
  font-style: italic;
}
...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// style.ts
export const CssBaseline = {
  root: ({ styleState }) => {
    const rootUrl = styleState.rootUrl || ''
    return `
      /* Lato Regular */
      @font-face {
        font-family: 'Lato';
        src: url('${rootUrl}themes/test/assets/fonts/Lato/Lato-Regular.ttf') format('truetype');
        font-weight: 400;
        font-style: normal;
      }

      /* Lato Italic */
      @font-face {
        font-family: 'Lato';
        src: url('${rootUrl}themes/test/assets/fonts/Lato/Lato-Italic.ttf') format('truetype');
        font-weight: 400;
        font-style: italic;
      }
      ...
    `
  }
}

Step 3: Register the font in your theme

Open the variables.json file inside your theme folder, and add the following configuration:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "ref": {
    "typeface": {
      "customFonts": [
        {
          "name": "Lato"
        }
      ],
      "fontFamily": "Lato"  // Sets Lato as the default font for the theme
    }
  }
}

Since the font is already loaded globally in your theme's styles, you don't need to provide a URL under customFonts.

Step 4: Apply the font

In your terminal, navigate to the client directory and run:

1
npm start

Then open Experience Builder. If everything is set up correctly, your app will now use the Lato font.

To confirm, go to the Theme Settings page under Typography—you should see Lato available in the font selector.