Typography
The theme provides a set of type sizes that work well together, and also with the layout grid.
Font family
You can change the font family with the theme.typography.fontFamily
property.
For instance, this example uses the system font instead of the default Roboto font:
<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</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">fontFamily</span><span class="token operator">:</span> <span class="token punctuation">[</span>
<span class="token string">'-apple-system'</span><span class="token punctuation">,</span>
<span class="token string">'BlinkMacSystemFont'</span><span class="token punctuation">,</span>
<span class="token string">'"Segoe UI"'</span><span class="token punctuation">,</span>
<span class="token string">'Roboto'</span><span class="token punctuation">,</span>
<span class="token string">'"Helvetica Neue"'</span><span class="token punctuation">,</span>
<span class="token string">'Arial'</span><span class="token punctuation">,</span>
<span class="token string">'sans-serif'</span><span class="token punctuation">,</span>
<span class="token string">'"Apple Color Emoji"'</span><span class="token punctuation">,</span>
<span class="token string">'"Segoe UI Emoji"'</span><span class="token punctuation">,</span>
<span class="token string">'"Segoe UI Symbol"'</span><span class="token punctuation">,</span>
<span class="token punctuation">]</span><span class="token punctuation">.</span><span class="token function">join</span><span class="token punctuation">(</span><span class="token string">','</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>
Self-hosted fonts
To self-host fonts, download the font files in ttf
, woff
, and/or woff2
formats and import them into your code.
⚠️ This requires that you have a plugin or loader in your build process that can handle loading ttf
, woff
, and
woff2
files. Fonts will not be embedded within your bundle. They will be loaded from your webserver instead of a
CDN.
<span class="token keyword">import</span> RalewayWoff2 <span class="token keyword">from</span> <span class="token string">'./fonts/Raleway-Regular.woff2'</span><span class="token punctuation">;</span>
Next, you need to change the theme to use this new font.
In order to globally define Raleway as a font face, the CssBaseline
component can be used (or any other CSS solution of your choice).
<span class="token keyword">import</span> RalewayWoff2 <span class="token keyword">from</span> <span class="token string">'./fonts/Raleway-Regular.woff2'</span><span class="token punctuation">;</span>
<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</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">fontFamily</span><span class="token operator">:</span> <span class="token string">'Raleway, Arial'</span><span class="token punctuation">,</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">MuiCssBaseline</span><span class="token operator">:</span> <span class="token punctuation">{</span>
<span class="token literal-property property">styleOverrides</span><span class="token operator">:</span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">
@font-face {
font-family: 'Raleway';
font-style: normal;
font-display: swap;
font-weight: 400;
src: local('Raleway'), local('Raleway-Regular'), url(</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>RalewayWoff2<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">) format('woff2');
unicodeRange: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF;
}
</span><span class="token template-punctuation 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 comment">// ...</span>
<span class="token keyword">return</span> <span class="token punctuation">(</span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">ThemeProvider</span></span> <span class="token attr-name">theme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>theme<span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">CssBaseline</span></span> <span class="token punctuation">/></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</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">fontFamily</span><span class="token operator">:</span> <span class="token string">'Raleway'</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">}</span></span>
<span class="token punctuation">></span></span>
Raleway
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span><span class="token class-name">Box</span></span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span><span class="token class-name">ThemeProvider</span></span><span class="token punctuation">></span></span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>
Note that if you want to add additional @font-face
declarations, you need to use the string CSS template syntax for adding style overrides, so that the previously defined @font-face
declarations won't be replaced.
Font size
Material UI uses rem
units for the font size.
The browser <html>
element default font size is 16px
, but browsers have an option to change this value,
so rem
units allow us to accommodate the user's settings, resulting in a better accessibility support.
Users change font size settings for all kinds of reasons, from poor eyesight to choosing optimum settings
for devices that can be vastly different in size and viewing distance.
To change the font-size of Material UI you can provide a fontSize
property.
The default value is 14px
.
<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</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 comment">// In Chinese and Japanese the characters are usually larger,</span>
<span class="token comment">// so a smaller fontsize may be appropriate.</span>
<span class="token literal-property property">fontSize</span><span class="token operator">:</span> <span class="token number">12</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>
The computed font size by the browser follows this mathematical equation:
Responsive font sizes
The theme.typography.*
variant properties map directly to the generated CSS.
You can use media queries inside them:
<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
theme<span class="token punctuation">.</span>typography<span class="token punctuation">.</span>h3 <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">'1.2rem'</span><span class="token punctuation">,</span>
<span class="token string-property property">'@media (min-width:600px)'</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">'1.5rem'</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">[</span>theme<span class="token punctuation">.</span>breakpoints<span class="token punctuation">.</span><span class="token function">up</span><span class="token punctuation">(</span><span class="token string">'md'</span><span class="token punctuation">)</span><span class="token punctuation">]</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">'2.4rem'</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>
Responsive h3
To automate this setup, you can use the responsiveFontSizes()
helper to make Typography font sizes in the theme responsive.
You can see this in action in the example below. Adjust your browser's window size, and notice how the font size changes as the width crosses the different breakpoints:
<span class="token keyword">import</span> <span class="token punctuation">{</span> createTheme<span class="token punctuation">,</span> responsiveFontSizes <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/material/styles'</span><span class="token punctuation">;</span>
<span class="token keyword">let</span> theme <span class="token operator">=</span> <span class="token function">createTheme</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
theme <span class="token operator">=</span> <span class="token function">responsiveFontSizes</span><span class="token punctuation">(</span>theme<span class="token punctuation">)</span><span class="token punctuation">;</span>
Responsive h3
Responsive h4
Responsive h5
Fluid font sizes
To be done: #15251.
HTML font size
You might want to change the <html>
element default font size. For instance, when using the 10px simplification.
The theme.typography.htmlFontSize
property is provided for this use case,
which tells Material UI what the font-size on the <html>
element is.
This is used to adjust the rem
value so the calculated font-size always match the specification.
<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</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 comment">// Tell Material UI what the font-size on the html element is.</span>
<span class="token literal-property property">htmlFontSize</span><span class="token operator">:</span> <span class="token number">10</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 selector">html</span> <span class="token punctuation">{</span>
<span class="token property">font-size</span><span class="token punctuation">:</span> 62.5%<span class="token punctuation">;</span> <span class="token comment">/* 62.5% of 16px = 10px */</span>
<span class="token punctuation">}</span>
You need to apply the above CSS on the html element of this page to see the below demo rendered correctly
body1
Variants
The typography object comes with 13 variants by default:
- h1
- h2
- h3
- h4
- h5
- h6
- subtitle1
- subtitle2
- body1
- body2
- button
- caption
- overline
Each of these variants can be customized individually:
<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</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">subtitle1</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 number">12</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token literal-property property">body1</span><span class="token operator">:</span> <span class="token punctuation">{</span>
<span class="token literal-property property">fontWeight</span><span class="token operator">:</span> <span class="token number">500</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token literal-property property">button</span><span class="token operator">:</span> <span class="token punctuation">{</span>
<span class="token literal-property property">fontStyle</span><span class="token operator">:</span> <span class="token string">'italic'</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>
subtitle
body1
Adding & disabling variants
In addition to using the default typography variants, you can add custom ones, or disable any you don't need. Here is what you need to do:
Step 1. Update the theme's typography object
The code snippet below adds a custom variant to the theme called poster
, and removes the default h3
variant:
<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</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">poster</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">'4rem'</span><span class="token punctuation">,</span>
<span class="token literal-property property">color</span><span class="token operator">:</span> <span class="token string">'red'</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token comment">// Disable h3 variant</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 punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
Step 2. (Optional) Set the default semantic element for your new variant
At this point, you can already use the new poster
variant, which will render a <span>
by default with your custom styles.
Sometimes you may want to default to a different HTML element for semantic purposes, or to replace the inline <span>
with a block-level element for styling purposes.
To do this, update the variantMapping
prop of the Typography
component globally, at the theme level:
<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</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">poster</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 number">64</span><span class="token punctuation">,</span>
<span class="token literal-property property">color</span><span class="token operator">:</span> <span class="token string">'red'</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token comment">// Disable h3 variant</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 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">MuiTypography</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">variantMapping</span><span class="token operator">:</span> <span class="token punctuation">{</span>
<span class="token comment">// Map the new variant to render a <h1> by default</span>
<span class="token literal-property property">poster</span><span class="token operator">:</span> <span class="token string">'h1'</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>
Step 3. Update the necessary typings (if you are using TypeScript)
You need to make sure that the typings for the theme's typography
variants and the Typography
's variant
prop reflects the new set of variants.
declare module <span class="token string">'@mui/material/styles'</span> <span class="token punctuation">{</span>
<span class="token keyword">interface</span> <span class="token class-name">TypographyVariants</span> <span class="token punctuation">{</span>
poster<span class="token operator">:</span> React<span class="token punctuation">.</span>CSSProperties<span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token comment">// allow configuration using `createTheme`</span>
<span class="token keyword">interface</span> <span class="token class-name">TypographyVariantsOptions</span> <span class="token punctuation">{</span>
poster<span class="token operator">?</span><span class="token operator">:</span> React<span class="token punctuation">.</span>CSSProperties<span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
<span class="token comment">// Update the Typography's variant prop options</span>
declare module <span class="token string">'@mui/material/Typography'</span> <span class="token punctuation">{</span>
<span class="token keyword">interface</span> <span class="token class-name">TypographyPropsVariantOverrides</span> <span class="token punctuation">{</span>
poster<span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">;</span>
h3<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>
Step 4. You can now use the new variant
poster
h3
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Typography</span></span> <span class="token attr-name">variant</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>poster<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>poster<span class="token tag"><span class="token tag"><span class="token punctuation"></</span><span class="token class-name">Typography</span></span><span class="token punctuation">></span></span><span class="token punctuation">;</span>
<span class="token comment">/* This variant is no longer supported. If you are using TypeScript it will give an error */</span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Typography</span></span> <span class="token attr-name">variant</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>h3<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>h3<span class="token tag"><span class="token tag"><span class="token punctuation"></</span><span class="token class-name">Typography</span></span><span class="token punctuation">></span></span><span class="token punctuation">;</span>
Default values
You can explore the default values of the typography using the theme explorer or by opening the dev tools console on this page (window.theme.typography
).