Skip to content
Edit this page

Typography

Use typography to present your design and content as clearly and efficiently as possible.

Levels

The Typography component has access to the typographic level scale defined in the theme. Use the level prop to toggle between scale values.

Keep in mind that the rendered HTML tag will change depending on the scale (e.g. "h1" will render an <h2> element, whereas "body1" renders as <p>).

display1

display2

h1

h2

h3

h4

h5
h6

body1

body2

body3body4body5

Change the semantic element

You can change the underlying element for an one-off situation with the component prop:

{
  /* There is already an h1 in the page so let's not duplicate it. */
}
<Typography level="h1" component="h2">
  h1. Heading
</Typography>;

You can change the tag mapping at the theme level as well:

const theme = extendTheme({
  components: {
    JoyTypography: {
      defaultProps: {
        levelMapping: {
          display1: 'h1',
          display2: 'h1',
          h1: 'h2',
          h2: 'h2',
          h3: 'h3',
          h4: 'h3',
          h5: 'h3',
          h6: 'h3',
          body1: 'p',
          body2: 'span',
          body3: 'span',
          body4: 'span',
          body5: 'span',
        },
      },
    },
  },
});

Adding new typography

To create your own typographic scale at the theme level, define the keys and values to theme.typography;

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

By doing that, you'll be able to use those levels from the level prop:

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

Remove built-in scale

If you want to start fresh with your own typographic scale, assign an undefined value to the built-in typography keys:

extendTheme({
  typography: {
    h1: undefined,
    h2: undefined,
    h3: undefined,
    h4: undefined,
    h5: undefined,
    h6: undefined,
    body1: undefined,
    body2: undefined,
    body3: undefined,
    // ...your scale
  },
});

If you use TypeScript, you have to remove them from the types as well:

// in your theme or index file
declare module '@mui/joy/styles' {
  interface TypographySystemOverrides {
    display1: false;
    display2: false;
    h1: false;
    h2: false;
    h3: false;
    h4: false;
    h5: false;
    h6: false;
    body1: false;
    body2: false;
    body3: false;
    body4: false;
    body5: false;
  }
}

Decorators

Use startDecorator and/or endDecorator for adding extra info to the text. Typography uses flexbox when start or end decorator elements are provided to ensure the center alignment.

The icon automatically adjusts to the scale

The display also changes to flexbox
123

Common examples

These are examples that demonstrate the composition of the Typography component and other components as decorators.

Inactive

$25

This example demonstrates multiple lines of the text.

🚨Simple alert using only Typography.

Nested typography

Nested Typography components will render as a <span> tag by default, unless the a value for the component prop is specified.

<Typography>
  Paragraph by default.
  <Typography fontWeight="lg">I am a span</Typography> {/* render as <span> */}
  <Typography component="strong">but strong</Typography> {/* render as <strong> */}
</Typography>

System props

As a CSS utility component, Typography supports every system properties. You can use them as prop directly on the component.

<Typography textColor="neutral.500" fontSize="sm" fontWeight="lg">

Accessibility

A few key factors to follow for an accessible typography: