Skip to content
+

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.

Typography

<Typography />

Playground

Basics

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

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

National Parks

Yosemite National Park

Yosemite National Park is a national park spanning 747,956 acres (1,169.4 sq mi; 3,025.2 km2) in the western Sierra Nevada of Central California.

Press Enter to start editing

Heading

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

h1: Lorem ipsum

h2: What is Lorem Ipsum?

h3: The standard Lorem Ipsum passage.

h4: The smallest headline of the page

Press Enter to start editing

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.

title-lg: Title of the component

body-lg: This is the description of the component that contain some information of it.

title-lg: Title of the component

body-md: This is the description of the component that contain some information of it.

title-lg: Title of the component

body-md: This is the description of the component that contain some information of it.

body-sm: Metadata, e.g. a date.

title-md: Title of the component

body-md: This is the description of the component that contain some information of it.

body-sm: Metadata, e.g. a date.

title-sm: Title of the component

body-sm: This is the description of the component that contain some information of it.

body-xs: Metadata, e.g. a date.

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).

Typography lets you create nested typography. Use your imagination to build wonderful user interface.

Press Enter to start editing

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.

h1

h2

h3

h4

title-lg

title-md

title-sm

body-lg

body-md

body-sm

body-xs
Press Enter to start editing

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.

The icon automatically adjusts to the scale

The display also changes to flexbox123

Press Enter to start editing

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.

Inactive

$25

This example demonstrates multiple lines of the text.

🚨Simple alert using only Typography.

+8.2% Since last month

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.