Skip to content

Latest commit

 

History

History
162 lines (116 loc) · 6.21 KB

theme-typography.md

File metadata and controls

162 lines (116 loc) · 6.21 KB
Raw

Theme typography

Learn about the 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.

{{"demo": "DefaultTypographySystem.js"}}

:::info CSS Baseline, Scoped CSS Baseline, and Typography are the only components that consume the theme typography directly.

This ensures that you can customize or even remove the default typography system without affecting other components. :::

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:

{{"demo": "CustomTypographyLevel.js"}}

Removing the default system

Use undefined as a value to remove any unneeded levels:

const customTheme = extendTheme({
  typography: {
    h5: undefined,
    h6: undefined,
    body4: undefined,
    body5: undefined,
  },
});

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

// You can put this to any file that's included in your tsconfig
declare module '@mui/joy/styles' {
  interface TypographySystemOverrides {
    h5: false;
    h6: false;
    body4: false;
    body5: false;
  }
}

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:

{{"demo": "NewTypographyLevel.js", "bg": true}}

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

// You can put this to any file that's included in your tsconfig
declare module '@mui/joy/styles' {
  interface TypographySystemOverrides {
    kbd: true;
  }
}

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:

    // use the `theme.typography.body2` styles
<Typography level="body2">Secondary info</Typography>

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

    <CssBaseline />

// inherits the `theme.typography.body1` styles
<p>Hello World</p>

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

    // to apply the `theme.typography.body2` styles:
<Box sx={{ typography: 'body2' }}>Small text</Box>

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

    import { styled } from '@mui/joy/styles';

const Tag = styled('span')((theme) => ({
  ...theme.typography.body2,
  color: 'inherit',
  borderRadius: theme.vars.radius.xs,
  boxShadow: theme.vars.shadow.sm,
  padding: '0.125em 0.375em',
}));

Common examples

Here is a collection of well-known typography systems that you can use with Joy UI.

Fluent (Microsoft)

<iframe src="https://codesandbox.io/embed/joy-ui-fluent-typography-system-j86fct?module=%2Fdemo.tsx&fontsize=14&hidenavigation=1&theme=dark&view=preview" style="width:100%; height:360px; border:0; border-radius: 4px; overflow:hidden;" title="Joy UI - Fluent Typography System" allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking" sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts" ></iframe>

Human Interface Guidelines (Apple)

<iframe src="https://codesandbox.io/embed/joy-ui-human-interface-guidelines-typography-system-lkuz4d?module=%2Fdemo.tsx&fontsize=14&hidenavigation=1&theme=dark&view=preview" style="width:100%; height:320px; border:0; border-radius: 4px; overflow:hidden;" title="Joy UI - Human Interface Guidelines Typography System" allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking" sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts" ></iframe>

Material Design 3 (Google)

<iframe src="https://codesandbox.io/embed/joy-ui-material-3-typography-system-lx044f?module=%2Fdemo.tsx&fontsize=14&hidenavigation=1&theme=dark&view=preview" style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;" title="Joy UI - Joy UI - Material 3 Typography System" allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking" sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts" ></iframe>

:::success Feel free to submit a PR to add your favorite typography system ❤️. :::