Theme typography

Learn about the default theme's 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.

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:

Removing the default system

Use undefined as a value to remove any unneeded levels:

<span class="token keyword">const</span> customTheme <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">typography</span><span class="token operator">:</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">body4</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
    <span class="token literal-property property">body5</span><span class="token operator">:</span> <span class="token keyword">undefined</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>

For TypeScript, you must augment the theme structure to exclude the default levels:

<span class="token comment">// You can put this to any file that's included in your tsconfig</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>
    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>
    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>

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:

For TypeScript, you must augment the theme structure to include the new level:

<span class="token comment">// You can put this to any file that's included in your tsconfig</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>
    kbd<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>

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:

  <span class="token comment">// use the `theme.typography.body2` styles</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>body2<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Secondary info<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>
  

  Copy (or $keyC)

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

  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">CssBaseline</span></span> <span class="token punctuation">/></span></span>
  
  <span class="token comment">// inherits the `theme.typography.body1` styles</span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>p</span><span class="token punctuation">></span></span>Hello World<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>p</span><span class="token punctuation">></span></span>
  

  Copy (or $keyC)

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

  <span class="token comment">// to apply the `theme.typography.body2` styles:</span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</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 string">'body2'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span><span class="token punctuation">></span></span>Small text<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Box</span></span><span class="token punctuation">></span></span>
  

  Copy (or $keyC)

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

  <span class="token keyword">import</span> <span class="token punctuation">{</span> styled <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/joy/styles'</span><span class="token punctuation">;</span>
  
  <span class="token keyword">const</span> Tag <span class="token operator">=</span> <span class="token function">styled</span><span class="token punctuation">(</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 parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
    <span class="token operator">...</span>theme<span class="token punctuation">.</span>typography<span class="token punctuation">.</span>body2<span class="token punctuation">,</span>
    <span class="token literal-property property">color</span><span class="token operator">:</span> <span class="token string">'inherit'</span><span class="token punctuation">,</span>
    <span class="token literal-property property">borderRadius</span><span class="token operator">:</span> theme<span class="token punctuation">.</span>vars<span class="token punctuation">.</span>radius<span class="token punctuation">.</span>xs<span class="token punctuation">,</span>
    <span class="token literal-property property">boxShadow</span><span class="token operator">:</span> theme<span class="token punctuation">.</span>vars<span class="token punctuation">.</span>shadow<span class="token punctuation">.</span>sm<span class="token punctuation">,</span>
    <span class="token literal-property property">padding</span><span class="token operator">:</span> <span class="token string">'0.125em 0.375em'</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>
  

  Copy (or $keyC)

Common examples

Here is a collection of well-known typography systems that you can use with Joy UI. Feel free to submit a PR to add your favorite if it's not here. ❤️

Microsoft's Fluent

• Design resource: Figma
• Font: Segoe UI

Apple's Human Interface Guidelines

• Design resource: Sketch library
• Font: San Francisco (SF)

Google's Material Design 3

• Design resource: Figma
• Font: Roboto