Skip to content
Edit this page
Skip to content

Theme typography

Learn about the typography system and how to customize it.

Joy UI includes a typography system within the theme to help you create consistent text across your application. You can customize the default system or start from scratch depending on your needs.

Default system

The default system consists of 13 built-in levels:

  • body1 - the baseline typography for the application, used as the default configuration in the Typography and CssBaseline components.
  • body2 through body5 - can be used for secondary and tertiary information.
  • The h1 to h6 levels follow the semantic HTML headings.
  • The display1 and display2 usually appear as taglines for marketing and landing pages.
display1
display2
h1
h2
h3
h4
h5
h6
body1
body2
body3
body4
body5

Customizing the default system

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

The example below illustrates the customization of the display1 level:

Gradient text
Press Enter to start editing

Removing the default system

Use undefined as a value to remove any unneeded levels:

const customTheme = extendTheme({
  typography: {
    h5: undefined,
    h6: undefined,
    body4: undefined,
    body5: 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 {
    h5: false;
    h6: false;
    body4: false;
    body5: false;
  }
}

Adding more levels

You can define a new level as a key-value pair in theme.typography, where the key is the name of the level and the value is an object containing CSS rules. The demo below shows how to add a new level called kbd:

Press ⌘ + k to search the documentation.

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;
  }
}

Usage

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

  • Typography component: use the level prop to change between theme typography levels:

    // use the `theme.typography.body2` styles
<Typography level="body2">Secondary info</Typography>

  • CSS Baseline component: by default, it applies the body1 level to the global stylesheet:

    <CssBaseline />

// inherits the `theme.typography.body1` styles
<p>Hello World</p>

  • sx prop: use typography: $level to get the specific theme typography level:

    // to apply the `theme.typography.body2` styles:
<Box sx={{ typography: 'body2' }}>Small text</Box>

  • styled: create a custom component and apply the style from theme.typography.* directly:

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

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

Common examples

Here is a collection of well-known typography systems that you can use with Joy UI.

Fluent (Microsoft)

Human Interface Guidelines (Apple)

Material Design 3 (Google)