Typography

The Typography component helps present design and content clearly and efficiently.

Introduction

The Typography component helps maintain a consistent design by providing a limited set of values to choose from and convenient props for building common designs faster.

Basics

import Typography from '@mui/joy/Typography';

The Typography component wraps around its content, and displays text with specific typographic styles and properties.

Heading

Use h1 through h4 to render a headline. The produced HTML element will match the semantic headings of the page structure.

Title and body

The title-* and body-* are commonly used in components.

We recommend to combine the title and body with the same or lower size when using them together. For example, title-lg and body-lg or title-md and body-sm.

Each level are designed to fit perfectly with the same size of the SvgIcon component.

Nested Typography

The Typography component renders as a <p> by default. Nested Typography components are rendered as <span> elements (unless customized by the component prop).

Customization

System props

As a CSS utility component, Typography supports every MUI System property. These properties can be used to customize the styling of the component and make it fit seamlessly with the overall design.

// Using the neutral color palette that defaults to the 500 value
<Typography color="neutral" fontSize="sm" fontWeight="lg" />

// Changing the specific element's color to neutral
<Typography textColor="neutral.300" fontSize="sm" fontWeight="lg" >

Levels

The level prop gives access to a pre-defined scale of typographic values defined in the theme. These values include various heading levels (h1, h2, h3, etc.) as well as body text levels (body-md, body-sm, etc) and can be used to apply consistent typography throughout your application. Additionally, you can also use the level prop to control the font size, weight, line height, and other typographic properties.

Semantic elements

To customize the semantic element used, you can use the component prop. This can be useful in situations where you want to use a different semantic element than the one assigned by the level prop. The component will render as the HTML element defined by component, but with the styles assigned to its respective level.

// There's already an h1 on the page so let's not add another one.

<Typography level="h1" component="h2">
  I render as an h2, but I have h1 styles
</Typography>

In a more efficient way, you can change the HTML mapping tags at the theme level.

const theme = extendTheme({
  components: {
    JoyTypography: {
      defaultProps: {
        levelMapping: {
          h1: 'h2',
          h2: 'h2',
          h3: 'h3',
          h4: 'h3',
          'title-lg': 'p',
          'title-md': 'p',
          'title-sm': 'p',
          'body-md': 'p',
          'body-sm': 'p',
          'body-xs': 'span',
        },
      },
    },
  },
});

Decorators

Use the startDecorator and endDecorator props to add supporting icons or elements to the Typography.

Typography scale

To create a custom typographic scale, you can define the keys and values in the theme.typography node at the theme level.

extendTheme({
  typography: {
    subtitle: {
      fontSize: 'var(--joy-fontSize-lg)',
      fontWeight: 'var(--joy-fontWeight-md)',
      // CSS selectors are also supported!
      '& + p': {
        marginTop: '4px',
      },
    },
    label: {
      fontSize: 'var(--joy-fontSize-sm)',
      fontWeight: 'var(--joy-fontWeight-lg)',
      lineHeight: 'var(--joy-lineHeight-lg)',
      marginBottom: '3px',
    },
  },
});

You can also access the newly created levels from the level prop:

<Typography level="subtitle">
<Typography level="label">

Removing the default scale

To remove any unused typographic levels (for example, if you're building your own fully custom scale), you can clear the built-in values by assigning undefined to them in the theme.

extendTheme({
  typography: {
    h1: undefined,
    h2: undefined,
    h3: undefined,
    h4: undefined,
    'title-lg': undefined,
    'title-md': undefined,
    'title-sm': undefined,
    'body-lg': undefined,
    'body-md': undefined,
    'body-sm': undefined,
    'body-xs': undefined,
    // ...your scale
  },
});

When using TypeScript, be sure to also remove the built-in typography tokens from the types.

// in your theme or index file
declare module '@mui/joy/styles' {
  interface TypographySystemOverrides {
    h1: false;
    h2: false;
    h3: false;
    h4: false;
    'title-lg': false;
    'title-md': false;
    'title-sm': false;
    'body-lg': false;
    'body-md': false;
    'body-sm': false;
    'body-xs': false;
  }
}

Common examples

The demo below illustrates multiple uses of the Typography component with others as decorators.

Accessibility

Here are some factors to ensure that your Typography components are accessible:

• Ensure sufficient color contrast between text and background, using a minimum of WCAG 2.0's color contrast ratio of 4.5:1.
• Use relative units such as rem for fontSize to accommodate the user's settings.
• Use a consistent heading hierarchy, and avoid skipping levels.
• Keep semantics and style separate by using the appropriate semantic elements(#semantic-elements).

Anatomy

The Typography component is composed of a single root <p> that's assigned the body-md class, unless these defaults are overridden by the level and/or component props.

When one Typography component is nested within another, the nested component renders as a <span> (unless customized as described above).

<p class="MuiTypography-root MuiTypography-body-md">
  <!-- Typography content -->
  <span class="MuiTypography-root MuiTypography-inherit">
    <!-- Nested Typography content -->
  </span>
</p>

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <Typography />