Skip to content
Influence Joy UI's 2024 roadmap! Participate in the latest Developer Survey
+

Theme typography

Learn about the default theme's typography system and how to customize it.

Default system

Joy UI's default theme includes a built-in typography system of 11 distinct levels—including semantic HTML headers as well as a comparable system for body text—to help you ensure consistency across your interface.

Level

Color

Font size

Font weight

Line height

h1

var(--joy-palette-text-primary, var(--joy-palette-neutral-800, #171A1C))

var(--joy-fontSize-xl4, 2.25rem)

var(--joy-fontWeight-xl, 700)

var(--joy-lineHeight-xs, 1.33334)

h2

var(--joy-palette-text-primary, var(--joy-palette-neutral-800, #171A1C))

var(--joy-fontSize-xl3, 1.875rem)

var(--joy-fontWeight-xl, 700)

var(--joy-lineHeight-xs, 1.33334)

h3

var(--joy-palette-text-primary, var(--joy-palette-neutral-800, #171A1C))

var(--joy-fontSize-xl2, 1.5rem)

var(--joy-fontWeight-lg, 600)

var(--joy-lineHeight-xs, 1.33334)

h4

var(--joy-palette-text-primary, var(--joy-palette-neutral-800, #171A1C))

var(--joy-fontSize-xl, 1.25rem)

var(--joy-fontWeight-lg, 600)

var(--joy-lineHeight-md, 1.5)

title-lg

var(--joy-palette-text-primary, var(--joy-palette-neutral-800, #171A1C))

var(--joy-fontSize-lg, 1.125rem)

var(--joy-fontWeight-lg, 600)

var(--joy-lineHeight-xs, 1.33334)

title-md

var(--joy-palette-text-primary, var(--joy-palette-neutral-800, #171A1C))

var(--joy-fontSize-md, 1rem)

var(--joy-fontWeight-md, 500)

var(--joy-lineHeight-md, 1.5)

title-sm

var(--joy-palette-text-primary, var(--joy-palette-neutral-800, #171A1C))

var(--joy-fontSize-sm, 0.875rem)

var(--joy-fontWeight-md, 500)

var(--joy-lineHeight-sm, 1.42858)

body-lg

var(--joy-palette-text-secondary, var(--joy-palette-neutral-700, #32383E))

var(--joy-fontSize-lg, 1.125rem)

-

var(--joy-lineHeight-md, 1.5)

body-md

var(--joy-palette-text-secondary, var(--joy-palette-neutral-700, #32383E))

var(--joy-fontSize-md, 1rem)

-

var(--joy-lineHeight-md, 1.5)

body-sm

var(--joy-palette-text-tertiary, var(--joy-palette-neutral-600, #555E68))

var(--joy-fontSize-sm, 0.875rem)

-

var(--joy-lineHeight-md, 1.5)

body-xs

var(--joy-palette-text-tertiary, var(--joy-palette-neutral-600, #555E68))

var(--joy-fontSize-xs, 0.75rem)

var(--joy-fontWeight-md, 500)

var(--joy-lineHeight-md, 1.5)

Usage

There are several ways that you can use the theme typography in your application:

Typography component

Use the level prop in the Typography component:

// use the `theme.typography['body-sm']` styles
<Typography level="body-sm">Secondary info</Typography>

CSS Baseline

The CSS Baseline component applies body-md as the default level on the global stylesheet:

<CssBaseline />

// inherits the `theme.typography['body-md']` styles
<p>Hello World</p>

sx prop

Customize the typographic styles via the sx prop using typography: 'some-level':

// to apply the `theme.typography['body-sm']` styles:
<Box sx={{ typography: 'body-sm' }}>Small text</Box>

Applying theme styles to custom components

Use the styled function to create a custom component and apply styles from theme.typography.*:

import { styled } from '@mui/joy/styles';

const Tag = styled('span')((theme) => ({
  ...theme.typography['body-sm'],
  color: 'inherit',
  borderRadius: theme.vars.radius.xs,
  boxShadow: theme.vars.shadow.sm,
  padding: '0.125em 0.375em',
}));

Customizations

To customize a default level, provide its name as a key along with an object containing the CSS rules as a value to the theme.typography node.

The example below illustrates the customization of the h1 level:

This is a gradient h1
Press Enter to start editing

Removing the default system

Use undefined as a value to remove any unwanted levels:

const customTheme = extendTheme({
  typography: {
    'title-sm': undefined,
    'title-xs': undefined,
  },
});

For TypeScript, you must augment the theme structure to exclude the default levels:

// You can put this to any file that's included in your tsconfig
declare module '@mui/joy/styles' {
  interface TypographySystemOverrides {
    'title-sm': false;
    'title-xs': false;
  }
}

Adding more levels

To add a new level, define it as a key-value pair in the theme.typography node, where the key is the name of the new level and the value is an object containing the CSS rules.

The demo below shows how to add a new level called kbd:

Press ⌘ + k to search the documentation.

Press Enter to start editing

For TypeScript, you must augment the theme structure to include the new level:

// You can put this to any file that's included in your tsconfig
declare module '@mui/joy/styles' {
  interface TypographySystemOverrides {
    kbd: true;
  }
}

Changing the default font

Joy UI uses the Inter font by default. To change it, override the theme's fontFamily property:

extendTheme({
  fontFamily: {
    display: 'Noto Sans', // applies to `h1`–`h4`
    body: 'Noto Sans', // applies to `title-*` and `body-*`
  },
});

Common examples

Here is a collection of well-known typography systems that you can use with Joy UI. Feel free to submit a PR to add your favorite if it's not here. ❤️

Microsoft's Fluent

Apple's Human Interface Guidelines

Google's Material Design 3