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

<span class="token keyword">import</span> Typography <span class="token keyword">from</span> <span class="token string">'@mui/joy/Typography'</span><span class="token punctuation">;</span>

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.

<Card variant="outlined" sx={{ maxWidth: 400 }}>
  <Typography level="h1">National Parks</Typography>
  <Typography level="h2" fontSize="xl" sx={{ mb: 0.5 }}>
    Yosemite National Park
  </Typography>
  <Typography level="body1">
    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.
  </Typography>
</Card>

<Card variant="outlined" sx={{ maxWidth: 400 }}>
  <Typography level="h1">National Parks</Typography>
  <Typography level="h2" fontSize="xl" sx={{ mb: 0.5 }}>
    Yosemite National Park
  </Typography>
  <Typography level="body1">
    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.
  </Typography>
</Card>

Press Enter to start editing

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.

<Typography mb={2} maxWidth={400} lineHeight="lg">
  Typography lets you create <Typography variant="soft">nested</Typography>{' '}
  typography. Use your{' '}
  <Typography variant="outlined" color="success">
    imagination
  </Typography>{' '}
  to build wonderful{' '}
  <Typography variant="solid" color="primary">
    user interface
  </Typography>
  .
</Typography>

<Typography mb={2} maxWidth={400} lineHeight="lg">
  Typography lets you create <Typography variant="soft">nested</Typography>{' '}
  typography. Use your{' '}
  <Typography variant="outlined" color="success">
    imagination
  </Typography>{' '}
  to build wonderful{' '}
  <Typography variant="solid" color="primary">
    user interface
  </Typography>
  .
</Typography>

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.


<span class="token comment">// Using the neutral color palette that defaults to the 500 value</span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Typography</span></span> <span class="token attr-name">color</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>neutral<span class="token punctuation">"</span></span> <span class="token attr-name">fontSize</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sm<span class="token punctuation">"</span></span> <span class="token attr-name">fontWeight</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>lg<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span>

<span class="token comment">// Changing the specific element's color to neutral</span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Typography</span></span> <span class="token attr-name">textColor</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>neutral.300<span class="token punctuation">"</span></span> <span class="token attr-name">fontSize</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sm<span class="token punctuation">"</span></span> <span class="token attr-name">fontWeight</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>lg<span class="token punctuation">"</span></span> <span class="token punctuation">></span></span>

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 (body1, body2, 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.

display1

display2

h1

h2

h3

h4

h5

h6

body1

body2

body3

body4body5

<Typography level="display1">display1</Typography>
<Typography level="display2">display2</Typography>
<Typography level="h1">h1</Typography>
<Typography level="h2">h2</Typography>
<Typography level="h3">h3</Typography>
<Typography level="h4">h4</Typography>
<Typography level="h5">h5</Typography>
<Typography level="h6">h6</Typography>
<Typography level="body1">body1</Typography>
<Typography level="body2">body2</Typography>
<Typography level="body3">body3</Typography>
<Typography level="body4">body4</Typography>
<Typography level="body5">body5</Typography>

<Typography level="display1">display1</Typography>
<Typography level="display2">display2</Typography>
<Typography level="h1">h1</Typography>
<Typography level="h2">h2</Typography>
<Typography level="h3">h3</Typography>
<Typography level="h4">h4</Typography>
<Typography level="h5">h5</Typography>
<Typography level="h6">h6</Typography>
<Typography level="body1">body1</Typography>
<Typography level="body2">body2</Typography>
<Typography level="body3">body3</Typography>
<Typography level="body4">body4</Typography>
<Typography level="body5">body5</Typography>

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.

<span class="token comment">// There's already an h1 on the page so let's not add another one.</span>

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Typography</span></span> <span class="token attr-name">level</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>h1<span class="token punctuation">"</span></span> <span class="token attr-name">component</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>h2<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
  <span class="token constant">I</span> render <span class="token keyword">as</span> an h2<span class="token punctuation">,</span> but <span class="token constant">I</span> have h1 styles
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Typography</span></span><span class="token punctuation">></span></span>

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

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">components</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">JoyTypography</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">defaultProps</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">levelMapping</span><span class="token operator">:</span> <span class="token punctuation">{</span>
          <span class="token literal-property property">display1</span><span class="token operator">:</span> <span class="token string">'h1'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">display2</span><span class="token operator">:</span> <span class="token string">'h1'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">h1</span><span class="token operator">:</span> <span class="token string">'h2'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">h2</span><span class="token operator">:</span> <span class="token string">'h2'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">h3</span><span class="token operator">:</span> <span class="token string">'h3'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">h4</span><span class="token operator">:</span> <span class="token string">'h3'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">h5</span><span class="token operator">:</span> <span class="token string">'h3'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">h6</span><span class="token operator">:</span> <span class="token string">'h3'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">body1</span><span class="token operator">:</span> <span class="token string">'p'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">body2</span><span class="token operator">:</span> <span class="token string">'span'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">body3</span><span class="token operator">:</span> <span class="token string">'span'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">body4</span><span class="token operator">:</span> <span class="token string">'span'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">body5</span><span class="token operator">:</span> <span class="token string">'span'</span><span class="token punctuation">,</span>
        <span class="token punctuation">}</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</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 flexbox
123

<Typography startDecorator={<InfoOutlined />} mb={2}>
  The icon automatically adjusts to the scale
</Typography>
<Typography
  level="h6"
  endDecorator={<Chip size="sm">123</Chip>}
  justifyContent="center"
>
  The display also changes to flexbox
</Typography>

<Typography startDecorator={<InfoOutlined />} mb={2}>
  The icon automatically adjusts to the scale
</Typography>
<Typography
  level="h6"
  endDecorator={<Chip size="sm">123</Chip>}
  justifyContent="center"
>
  The display also changes to flexbox
</Typography>

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.

<span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">typography</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">subtitle</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">fontSize</span><span class="token operator">:</span> <span class="token string">'var(--joy-fontSize-lg)'</span><span class="token punctuation">,</span>
      <span class="token literal-property property">fontWeight</span><span class="token operator">:</span> <span class="token string">'var(--joy-fontWeight-md)'</span><span class="token punctuation">,</span>
      <span class="token comment">// CSS selectors are also supported!</span>
      <span class="token string-property property">'&amp; + p'</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">marginTop</span><span class="token operator">:</span> <span class="token string">'4px'</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token literal-property property">label</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">fontSize</span><span class="token operator">:</span> <span class="token string">'var(--joy-fontSize-sm)'</span><span class="token punctuation">,</span>
      <span class="token literal-property property">fontWeight</span><span class="token operator">:</span> <span class="token string">'var(--joy-fontWeight-lg)'</span><span class="token punctuation">,</span>
      <span class="token literal-property property">lineHeight</span><span class="token operator">:</span> <span class="token string">'var(--joy-lineHeight-lg)'</span><span class="token punctuation">,</span>
      <span class="token literal-property property">marginBottom</span><span class="token operator">:</span> <span class="token string">'3px'</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

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

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Typography</span></span> <span class="token attr-name">level</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>subtitle<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Typography</span></span> <span class="token attr-name">level</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>label<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>

When using TypeScript, make sure to add module augmentation for the new theme values.

<span class="token comment">// in your theme or index file</span>
declare module <span class="token string">'@mui/joy/styles'</span> <span class="token punctuation">{</span>
  <span class="token keyword">interface</span> <span class="token class-name">TypographySystemOverrides</span> <span class="token punctuation">{</span>
    subtitle<span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">;</span>
    label<span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>

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.

<span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">typography</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">h1</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
    <span class="token literal-property property">h2</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
    <span class="token literal-property property">h3</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
    <span class="token literal-property property">h4</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
    <span class="token literal-property property">h5</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
    <span class="token literal-property property">h6</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
    <span class="token literal-property property">body1</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
    <span class="token literal-property property">body2</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
    <span class="token literal-property property">body3</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
    <span class="token comment">// ...your scale</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

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

<span class="token comment">// in your theme or index file</span>
declare module <span class="token string">'@mui/joy/styles'</span> <span class="token punctuation">{</span>
  <span class="token keyword">interface</span> <span class="token class-name">TypographySystemOverrides</span> <span class="token punctuation">{</span>
    display1<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    display2<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    h1<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    h2<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    h3<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    h4<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    h5<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    h6<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    body1<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    body2<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    body3<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    body4<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    body5<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>

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.

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

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>p</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>MuiTypography-root MuiTypography-body1<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
  <span class="token comment">&lt;!-- Typography content --></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>span</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>MuiTypography-root MuiTypography-inherit<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
    <span class="token comment">&lt;!-- Nested Typography content --></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>span</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>p</span><span class="token punctuation">></span></span>

API

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

<Typography />

Typography

Introduction

Typography

Playground

Basics

National Parks

Yosemite National Park

Nested Typography

Customization

System props

Levels

display1

display2

h1

h2

h3

h4

h5

h6

Semantic elements

Decorators

The display also changes to flexbox123

Typography scale

Removing the default scale

Common examples

Accessibility

Anatomy

API

The display also changes to flexbox
123