SharePoint Brand Center Typography in SPFx: Fluent UI v8 & v9

SharePoint Brand Center typography in SPFx connects the fonts selected for a modern SharePoint site with the text in your custom web parts. Without an explicit mapping, Fluent UI controls can keep their default font family even when surrounding SharePoint content follows the selected font package.

This guide expands the source PDF into a practical implementation for native styles, Fluent UI v8 ThemeProvider, and Fluent UI v9 FluentProvider. It includes reusable adapters, role-specific font choices, troubleshooting, and a release checklist.

Quick answer: use documented SharePoint font-family custom properties, map them into the styling API for your actual Fluent UI version, keep providers scoped to the web part, and validate the result on a real SharePoint page. Do not copy an illustrative token or a v9 theme shape into a v8 component.

The hero and PDF interface drawings are conceptual illustrations. The code focuses on font-family integration; it does not recreate the whole SharePoint design system. References were checked on 17 October 2026. Verify the dependency versions and host behavior in your own supported SPFx project.

1. Why Does My SPFx Web Part Ignore Brand Center Fonts?

The most common cause is that the custom component owns a font rule that takes precedence over inherited page styling. A hardcoded family, a Fluent theme default, a local component override, or a missing provider mapping can all produce that result.

Trace the chain from the selected site font package to the available custom property, the web-part adapter, the component style, and the actual rendered font. A matching heading on a neighboring SharePoint web part does not establish that your own component consumes the same role.

Layer	What to verify
Site configuration	The intended font package is applied and native SharePoint content responds.
Font slot	The documented property is available in the component’s styling context.
Adapter	The chosen body, heading, or interactive family reaches the correct Fluent API.
Component	The computed rule is not replaced by a more specific style.
Font resource	The intended face actually loads and renders the required characters.

Microsoft’s SPFx Brand Center font reference documents the custom properties. Keep that reference separate from the color-theme APIs you already use.

2. Understand Font Packages and Typography Roles

A font package supplies a coordinated approach to site typography. Microsoft’s font-package documentation distinguishes display and content families and maps typography into roles.

Choose a role based on what the text does. A web-part heading, a paragraph, a small caption, and a button label need not share the same family. Matching every element to one heading font can harm readability and lose the intended design hierarchy.

Example role	Documented family property	Typical use in this guide
Small caption role	--fontFamilyCustomFont100	Supporting caption where appropriate.
Interactive label role	--fontFamilyCustomFont600	Button label.
Paragraph role	--fontFamilyCustomFont800	Main body copy.
Heading role	--fontFamilyCustomFont1300	Web-part heading.
Page-title role	--fontFamilyCustomFont1600	Page or site title contexts, not every component heading.

Consult the full official slot reference for your component’s role. The number in a CustomFont name is a role identifier, not a CSS font-weight value. Do not invent matching font-size or line-height property names from this naming pattern.

3. Verify the SPFx and Fluent UI Versions First

Check the project’s actual SPFx, React, TypeScript, and Fluent UI dependencies before adopting a sample. Microsoft recommends the Fluent UI version supplied for the SPFx project and publishes an SPFx compatibility matrix.

Fluent UI v8 normally uses @fluentui/react. Fluent UI v9 uses @fluentui/react-components. Their providers, theme types, and styling utilities differ. Import a component and its theme integration from the appropriate version.

Concern	Fluent UI v8	Fluent UI v9
Scoped provider	ThemeProvider	FluentProvider
Font mapping	ITheme.fonts and component styles.	Flat font tokens such as fontFamilyBase and component classes.
Role-specific styles	Font variants and supported style slots.	Supported tokens, typography styles, and makeStyles.
Integration boundary	Map a real v8 base theme.	Map a real v9 base theme.

Do not upgrade the project’s React version solely to make a copied sample install. A v9 typography example is not a blanket recommendation to migrate an existing v8 SPFx solution. Review Microsoft’s Fluent UI integration guidance and validate the exact package combination.

4. Define One Small Font Adapter

Centralize the selected roles so multiple components use the same choices. These constants contain documented SharePoint property names and a usable literal fallback stack.

export const brandFonts = {
  body: 'var(--fontFamilyCustomFont800, "Segoe UI", sans-serif)',
  heading: 'var(--fontFamilyCustomFont1300, "Segoe UI", sans-serif)',
  interactive: 'var(--fontFamilyCustomFont600, "Segoe UI", sans-serif)',
};

Save this as fonts.ts beside the example components, or place it in your approved shared UI package. A literal fallback is intentional: a site may not expose a custom slot, or a particular host may not provide Brand Center context.

Keep font fallback and loading separate. A valid CSS family string does not prove the font file loaded, and the browser can use another face for characters missing from the requested font.

5. Use the Roles in Native SPFx Styles

For elements you own, use scoped module styles. Assign a class directly to a native control when you want it to inherit the surrounding family. Avoid changing the page’s global typography.

.card { font-family: var(--fontFamilyCustomFont800, "Segoe UI", sans-serif); }
.title { font-family: var(--fontFamilyCustomFont1300, "Segoe UI", sans-serif); }
.nativeControl { font-family: inherit; }

The module root applies the body role. A separate heading class applies the heading role. Assign the native-control class only where appropriate; a blanket reset across all buttons and inputs can override the carefully chosen typography of nested Fluent controls.

Keep semantic headings, readable line heights, and suitable text sizes. A font-family integration does not automatically apply every Brand Center size, weight, spacing, or accessibility decision.

6. Integrate Brand Fonts With Fluent UI v8

The v8 example receives the application’s existing ITheme, copies its font variants, and changes their families while preserving other theme properties. It maps the selected heading variant explicitly and supplies the button’s label family through a supported component style slot.

import * as React from 'react';
import {
  DefaultButton, IFontStyles, ITheme, Text, ThemeProvider,
} from '@fluentui/react';
import { brandFonts } from './fonts';

export function toBrandV8Theme(baseTheme: ITheme): ITheme {
  const fonts: IFontStyles = { ...baseTheme.fonts };
  (Object.keys(fonts) as Array<keyof IFontStyles>).forEach(key => {
    fonts[key] = { ...fonts[key], fontFamily: brandFonts.body };
  });
  fonts.xLarge = { ...fonts.xLarge, fontFamily: brandFonts.heading };
  return { ...baseTheme, fonts };
}

export function BrandV8(props: { baseTheme: ITheme }): JSX.Element {
  const theme = React.useMemo(
    () => toBrandV8Theme(props.baseTheme), [props.baseTheme]
  );
  return (
    <ThemeProvider theme={theme}>
      <Text as="h2" variant="xLarge">Team resources</Text>
      <Text as="p" variant="medium">Approved guidance for your team.</Text>
      <DefaultButton
        text="Explore resources"
        styles={{ label: { fontFamily: brandFonts.interactive } }}
      />
    </ThemeProvider>
  );
}

Save this as BrandV8.tsx with the shared fonts.ts. Supply the real v8 base theme your web part already derives from its host. An SPFx theme object and a Fluent v8 ITheme are not interchangeable just because their names sound similar; keep the existing typed host adapter.

The adapter changes families only. Review any custom variants and component styles in your application. The example’s xLarge mapping is a chosen heading treatment, not a promise that every control automatically uses the same variant.

The official v8 ThemeProvider documentation describes contextual theming. Scope the provider to your web part and retain the host’s color and section-background behavior. Avoid using a global theme mutation to repair one component.

7. Integrate Brand Fonts With Fluent UI v9

A v9 theme exposes flat tokens such as fontFamilyBase. There is no general nested typography.fontFamily object that replaces this API. Start from the v9 base theme already selected by your host integration, override the body family, and use role-specific classes for the heading and action.

import * as React from 'react';
import {
  Button, FluentProvider, makeStyles, Text, Theme, typographyStyles,
} from '@fluentui/react-components';
import { brandFonts } from './fonts';

export function toBrandV9Theme(baseTheme: Theme): Theme {
  return { ...baseTheme, fontFamilyBase: brandFonts.body };
}

const useStyles = makeStyles({
  heading: { ...typographyStyles.title3, fontFamily: brandFonts.heading },
  action: { fontFamily: brandFonts.interactive },
});

export function BrandV9(props: { baseTheme: Theme }): JSX.Element {
  const styles = useStyles();
  const theme = React.useMemo(
    () => toBrandV9Theme(props.baseTheme), [props.baseTheme]
  );
  return (
    <FluentProvider theme={theme}>
      <h2 className={styles.heading}>
        Team resources
      </h2>
      <Text as="p">Approved guidance for your team.</Text>
      <Button className={styles.action}>Explore resources</Button>
    </FluentProvider>
  );
}

These helper examples were type-checked together with React 17.0.1, TypeScript 5.8, and separately installed Fluent UI v8 and v9 packages. Adapter checks confirmed preservation of base color properties. This is not a tenant runtime test; complete the SharePoint page checks below.

Save this as BrandV9.tsx beside fonts.ts. The native h2 supplies heading semantics; typographyStyles.title3 supplies Fluent metrics before the family override. Microsoft’s v9 token types define the flat theme structure and typography-style names.

Supply a real v9 Theme. Passing a SharePoint theme object directly, or always substituting a generic light theme, does not establish correct site colors or dark-mode behavior. Keep your color adapter and host theme updates working.

Avoid a circular fallback: when setting v9 fontFamilyBase, do not define its value in terms of the same generated --fontFamilyBase property. The adapter uses the SharePoint custom role with a literal fallback instead.

The sample changes neither monospace nor numeric typography globally. Override those only when there is a clear role and validation requirement. A body-font integration should not silently replace code text with a decorative display face.

8. Keep Providers, Pop-Ups, and Theme Changes in Scope

Context matters twice: React components consume a provider, while CSS custom properties resolve through DOM scope. Inspect both when a dialog or menu uses a different family from the inline control.

Portaled content can render in a different DOM location. Verify your Fluent version’s supported portal or mount configuration and inspect the resulting element. Do not assume that every pop-up inherits a SharePoint role property from the same ancestor as the web-part root.

Keep provider scope local and test more than one web part on the same page. A global rule such as changing body or broadly targeting generated library class names can create unrelated regressions.

CSS variables can respond to changes in their styling context without taking a one-time JavaScript snapshot. Your host color-theme integration still needs its supported lifecycle handling. Test a font-package change and a theme change as separate scenarios.

9. Inspect the Actual Font in Browser Developer Tools

Select an affected element and examine the winning font-family rule, available custom properties, and the fonts actually used to render the text. In Chromium DevTools, the following read-only console example uses the currently selected element:

const element = $0;
const styles = getComputedStyle(element);
console.table({
  bodySlot: styles.getPropertyValue('--fontFamilyCustomFont800'),
  headingSlot: styles.getPropertyValue('--fontFamilyCustomFont1300'),
  computedFamily: styles.fontFamily,
  computedWeight: styles.fontWeight,
});

The $0 helper belongs to DevTools, not application code. Check the browser’s rendered-font information as well as the computed family list. In the Network panel, inspect font requests and failures; a fallback can make the page look usable while hiding a loading problem.

Start with a heading, a paragraph, a button, and a pop-up control. If only one fails, investigate that component’s styles and provider path before changing the whole adapter.

10. Test on a Real SharePoint Page

Microsoft’s SPFx font guide states that the hosted workbench does not support Brand Center custom fonts. Validate the web part on an actual site page where the intended font package is applied.

Use the local development or debug workflow supported by your SPFx toolchain, then confirm the packaged release on an approved test site. Do not copy a build command from a different SPFx generation without checking the project’s scripts.

Test	Evidence to capture
Configured Brand Center package	Native SharePoint text and your component follow the intended roles.
No custom slot available	The fallback remains readable without layout failure.
Font-package change	Body, heading, and interactive text follow the new selection as expected.
Site color or section change	Text and backgrounds retain appropriate contrast and host-theme behavior.
Multiple web parts and pop-ups	One component’s provider does not disturb another’s fonts.
Mobile width, zoom, and long content	Headings, buttons, labels, and translated content remain usable.
Supported browsers and character sets	Font loading and glyph fallback behave as required.

Check keyboard focus, heading order, and labels alongside visual readability. Typography quality includes using the interface successfully, not merely matching a screenshot.

11. Troubleshoot Common Brand Font Problems

Symptom	Likely cause to investigate	Verification
All web-part text uses the default face	Missing role property, wrong host context, or adapter not applied.	The chosen property resolves and the component renders the intended face.
Only a button or input differs	Component-specific style overrides the parent family.	The relevant control slot or class uses the intended interactive role.
v9 override has no effect	Wrong theme shape, incorrect provider, or a later class override.	The actual flat token and winning component rule are correct.
Inline controls match but a menu does not	Provider or DOM scope differs for portaled content.	The mounted pop-up receives the required theme and role properties.
The family looks correct but the text differs	Font request failure, unavailable weight, missing glyphs, or another rendered face.	Rendered-font and network evidence confirms the expected resource.
A workbench test differs from a site page	The hosted workbench lacks the required Brand Center font context.	The packaged component is validated on a configured SharePoint page.

12. Build a Reusable Typography Integration

Keep the role constants, v8 adapter, and v9 adapter distinct but managed together. Review role mappings once, then reuse them across web parts with versioned changes and a small reference page for regression testing.

For an intranet resource card, the acceptance criteria might be: the title uses the approved heading role, body copy remains readable, the action uses the interactive role, and a dialog behaves consistently. Capture those results on a configured site and one with missing custom slots.

Preserve the font assets and loading strategy managed by the organization. Do not upload a duplicate font or invent an @font-face URL merely because a component has not consumed the existing role correctly.

Use the SPFx React guide for component architecture, the SPFx troubleshooting guide for broader failures, and the SPFx learning hub for related development topics.

13. Release Checklist

1. Confirm the SPFx and Fluent UI versions and their supported React dependency.
2. Apply an approved font package and verify native SharePoint typography.
3. Select documented roles for body, heading, caption, and interactive text as needed.
4. Use scoped native styles or the correct Fluent provider and adapter.
5. Preserve the host’s colors, section behavior, and theme lifecycle.
6. Verify real font resources, fallback behavior, and component-specific overrides.
7. Test dialogs, menus, multiple web parts, mobile layouts, zoom, and required languages.
8. Validate the packaged solution on an actual SharePoint site page.
9. Keep the role mapping, dependency versions, and acceptance evidence with the release.

Practical next step: select one heading and one button in your current web part. Trace their rendered fonts back through the component styles and provider to the available SharePoint role. Repair that path, then repeat the test after changing the site font package.