diff --git a/docs/data/joy/components/typography/TypographyBasics.js b/docs/data/joy/components/typography/TypographyBasics.js new file mode 100644 index 00000000000000..9c8abb0cbc09f7 --- /dev/null +++ b/docs/data/joy/components/typography/TypographyBasics.js @@ -0,0 +1,18 @@ +import * as React from 'react'; +import Card from '@mui/joy/Card'; +import Typography from '@mui/joy/Typography'; + +export default function TypographyBasics() { + return ( + + 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. + + + ); +} diff --git a/docs/data/joy/components/typography/TypographyBasics.tsx b/docs/data/joy/components/typography/TypographyBasics.tsx new file mode 100644 index 00000000000000..9c8abb0cbc09f7 --- /dev/null +++ b/docs/data/joy/components/typography/TypographyBasics.tsx @@ -0,0 +1,18 @@ +import * as React from 'react'; +import Card from '@mui/joy/Card'; +import Typography from '@mui/joy/Typography'; + +export default function TypographyBasics() { + return ( + + 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. + + + ); +} diff --git a/docs/data/joy/components/typography/TypographyBasics.tsx.preview b/docs/data/joy/components/typography/TypographyBasics.tsx.preview new file mode 100644 index 00000000000000..9b6e680a26a9c9 --- /dev/null +++ b/docs/data/joy/components/typography/TypographyBasics.tsx.preview @@ -0,0 +1,10 @@ + + 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. + + \ No newline at end of file diff --git a/docs/data/joy/components/typography/typography.md b/docs/data/joy/components/typography/typography.md index 1936cc9d95900f..8ff5252655e40d 100644 --- a/docs/data/joy/components/typography/typography.md +++ b/docs/data/joy/components/typography/typography.md @@ -6,53 +6,77 @@ githubLabel: 'component: Typography' # Typography -

Use typography to present your design and content as clearly and efficiently as possible.

+

The Typography component helps present design and content clearly and efficiently.

## Introduction -The `Typography` component helps you maintain a consistent design by offering a limited set of values to choose while also providing a few convenient props that makes common designs faster to build. -Joy UI's uses [_Public Sans_](https://fonts.google.com/specimen/Public+Sans?query=public), a Google Font, as the default typeface. +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. -## Component - -After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements: +## Basics ```jsx import Typography from '@mui/joy/Typography'; - -export default function MyApp() { - return Hello world!; -} ``` +The Typography component wraps around its content, and displays text with specific typographic styles and properties. + +{{"demo": "TypographyBasics.js"}} + +### Nested Typography + +The Typography component renders as a `

` by default. +Nested Typography components are rendered as `` elements (unless customized by [the `component` prop](#semantic-elements)). + +{{"demo": "NestedTypography.js"}} + +## Customization + ### System props -As a CSS utility component, `Typography` supports every [`system`](/system/properties/) property. +As a CSS utility component, Typography supports every [MUI System](/system/properties/) property. +These properties can be used to customize the styling of the component and make it fit seamlessly with the overall design. + +:::warning +Note that the `color` prop is an exception, it refers to the palette instead of the text color specifically. To set the text color, use the `textColor` prop. +::: ```jsx - + +// Using the neutral color palette that defaults to the 500 value + + +// Changing the specific element's color to neutral + + ``` +### 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. + :::warning -The `color` prop is an exception, though! -It actually refers to the palette being used and not specifically the text color. -To override that instead, use the `textColor` prop. +Keep in mind that each level renders a specific HTML tag (e.g. "h1" renders as an `

` element, "body1" renders as a `

`, etc.) ::: -### Changing the semantic element +{{"demo": "TypographyScales.js"}} + +### Semantic elements -To control which HTML tag should be rendered in a given, one-off, situation, use the `component` prop. +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`. ```jsx -{ - /* There is already an h1 in the page so let's not duplicate it. */ -} +// There's already an h1 on the page so let's not add another one. + - h1. Heading -; + I render as an h2, but I have h1 styles + ``` -To control this in a much more efficient way, change the HTML mapping tags at the theme level. +In a more efficient way, you can change the HTML mapping tags at the theme level. ```js const theme = extendTheme({ @@ -80,40 +104,15 @@ const theme = extendTheme({ }); ``` -### Levels - -The `Typography` component has access to the typographic level scale defined in the theme. -Use the `level` prop to control the scale value. - -:::warning -Keep in mind that each level renders a specific HTML tag (e.g. "h1" renders as an `

` element, "body1" renders as a `

`, etc.) -::: - -{{"demo": "TypographyScales.js"}} - ### Decorators -Use the `startDecorator` and/or `endDecorator` props to add supporting icons or elements to the typography. +Use the `startDecorator` and `endDecorator` props to add supporting icons or elements to the Typography. {{"demo": "TypographyDecorators.js"}} -### Nested typography +### Typography scale -Nested `Typography` components will render as a `` tag by default, unless a value for the `component` prop in each component is specified. - -```js - - Paragraph by default. - I am a span {/* render as */} - but strong {/* render as */} - -``` - -{{"demo": "NestedTypography.js"}} - -## Create a new scale - -To create your own typographic scale at the theme level, define the keys and values to `theme.typography` node. +To create a custom typographic scale, you can define the keys and values in the `theme.typography` node at the theme level. ```js extendTheme({ @@ -121,7 +120,7 @@ extendTheme({ subtitle: { fontSize: 'var(--joy-fontSize-lg)', fontWeight: 'var(--joy-fontWeight-md)', - // CSS selector is also supported! + // CSS selectors are also supported! '& + p': { marginTop: '4px', }, @@ -136,7 +135,7 @@ extendTheme({ }); ``` -You can also access the newly created levels from the `level` prop. +You can also access the newly created levels from the `level` prop: ```js @@ -144,7 +143,7 @@ You can also access the newly created levels from the `level` prop. ``` :::warning -When using _TypeScript_, make sure to add module augmentation for the new theme values. +When using TypeScript, make sure to add module augmentation for the new theme values. ```ts // in your theme or index file @@ -158,9 +157,9 @@ declare module '@mui/joy/styles' { ::: -## Remove the built-in scale +#### Removing the default scale -To start fresh with your own typographic scale, assign an `undefined` value to the built-in typography tokens in the theme. +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. ```js extendTheme({ @@ -179,7 +178,7 @@ extendTheme({ }); ``` -Make sure to remove them from the types as well if using **TypeScript**. +When using TypeScript, be sure to also remove the built-in typography tokens from the types. ```ts // in your theme or index file @@ -202,17 +201,32 @@ declare module '@mui/joy/styles' { } ``` +## Common examples + +The demo below illustrates multiple uses of the Typography component with others as [decorators](#decorators). + +{{"demo": "DecoratorExamples.js"}} + ## Accessibility -Here are a few tips to make sure you have an accessible typography component: +Here are some factors to ensure that your Typography components are accessible: -- **Color contrast**: always provide enough contrast between text and background. The minimum recommended [WCAG 2.0 color contrast ratio](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) is 4.5:1. -- **Dynamic units**: use [relative units (rem)](/material-ui/customization/typography/#font-size) for `fontSize` to accommodate the user's settings. -- **Heading hierarchy**: [don't skip](https://www.w3.org/WAI/tutorials/page-structure/headings/) heading levels. - Remember to [separate the semantics from the style](#changing-the-semantic-element). +- Ensure sufficient color contrast between text and background, using a minimum of [WCAG 2.0's color contrast ratio](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) of 4.5:1. +- Use [relative units](/material-ui/customization/typography/#font-size) such as rem for `fontSize` to accommodate the user's settings. +- Use a consistent [heading hierarchy](https://www.w3.org/WAI/tutorials/page-structure/headings/), and avoid skipping levels. +- Keep semantics and style separate by using the appropriate semantic elements(#semantic-elements). -## Common examples +## Anatomy -Examples showcasing how to compose designs with the `Typography` component and others as decorators. +The Typography component is composed of a single root `

` that's assigned the `body1` class, unless these defaults are overridden by the [`level`](#levels) and/or [`component`](#semantic-elements) props. -{{"demo": "DecoratorExamples.js"}} +When one Typography component is nested within another, the nested component renders as a `` (unless customized as described above). + +```html +

+ + + + +

+``` diff --git a/examples/gatsby/gatsby-config.js b/examples/gatsby/gatsby-config.js deleted file mode 100644 index 1c57408c4e725a..00000000000000 --- a/examples/gatsby/gatsby-config.js +++ /dev/null @@ -1,12 +0,0 @@ -module.exports = { - plugins: [ - 'gatsby-plugin-top-layout', - 'gatsby-plugin-react-helmet', - // If you want to use styled components you should add the plugin here. - // 'gatsby-plugin-styled-components', - 'gatsby-plugin-mui-emotion', - ], - siteMetadata: { - title: 'My page', - }, -}; diff --git a/examples/gatsby/plugins/gatsby-plugin-mui-emotion/gatsby-browser.js b/examples/gatsby/plugins/gatsby-plugin-mui-emotion/gatsby-browser.js deleted file mode 100644 index e2e89a449f21ff..00000000000000 --- a/examples/gatsby/plugins/gatsby-plugin-mui-emotion/gatsby-browser.js +++ /dev/null @@ -1,10 +0,0 @@ -/* eslint-disable import/prefer-default-export */ -import * as React from 'react'; -import { CacheProvider } from '@emotion/react'; -import getEmotionCache from './getEmotionCache'; - -const cache = getEmotionCache(); - -export const wrapRootElement = ({ element }) => { - return {element}; -}; diff --git a/examples/gatsby/plugins/gatsby-plugin-mui-emotion/gatsby-ssr.js b/examples/gatsby/plugins/gatsby-plugin-mui-emotion/gatsby-ssr.js deleted file mode 100644 index 388bb20bb069aa..00000000000000 --- a/examples/gatsby/plugins/gatsby-plugin-mui-emotion/gatsby-ssr.js +++ /dev/null @@ -1,43 +0,0 @@ -import * as React from 'react'; -import { CacheProvider } from '@emotion/react'; -import createEmotionServer from '@emotion/server/create-instance'; -import { renderToString } from 'react-dom/server'; -import getEmotionCache from './getEmotionCache'; - -// Inject MUI styles first to match with the prepend: true configuration. -export const onPreRenderHTML = ({ getHeadComponents, replaceHeadComponents }) => { - const headComponents = getHeadComponents(); - headComponents.sort((x, y) => { - if (x.key === 'emotion-css-global' || x.key === 'emotion-css') { - return -1; - } - if (y.key === 'style') { - return 1; - } - return 0; - }); - replaceHeadComponents(headComponents); -}; - -export const replaceRenderer = ({ bodyComponent, setHeadComponents, replaceBodyHTMLString }) => { - const cache = getEmotionCache(); - const { extractCriticalToChunks } = createEmotionServer(cache); - - const emotionStyles = extractCriticalToChunks( - renderToString({bodyComponent}), - ); - - setHeadComponents( - emotionStyles.styles.map((style) => ( -