005cf56baf
3.4 KiB
Right-to-left support
Learn how to implement right-to-left (RTL) text with Material UI to support languages such as Arabic, Persian, and Hebrew.
Setup
This guide outlines the three steps necessary to change the direction of text-based components in Material UI to support RTL languages, as shown in the demo below:
{{"demo": "RtlDemo.js"}}
1. Set the HTML direction
You can set the text direction either globally (across the entire app) or locally (specific to individual components), depending on your use case.
Globally
Add dir="rtl" to the app's root <html> to set the global text direction:
<html dir="rtl"></html>
If you can't set the dir attribute directly on the root <html> element, as a workaround, use the JavaScript API before the page is rendered:
document.documentElement.setAttribute('dir', 'rtl');
Locally
Add the dir="rtl" attribute to any other HTML element or React component if you need to limit the scope of the text direction to that element and its children.
:::warning
Components that use React portals (like the Dialog) do not inherit the dir attribute from parents, because they actually render outside of their parental DOM trees.
You must apply the dir attribute directly to these components if it's not globally defined as right-to-left:
<Box dir="rtl">
<Dialog /> // ❌ this Dialog will still be left-to-right (the default)
</Box>
<Box dir="rtl">
<Dialog dir="rtl" /> // ✅ this Dialog will be right-to-left as intended
</Box>
:::
2. Set the theme direction
Use the createTheme() API to set the theme direction to 'rtl':
import { createTheme } from '@mui/material/styles';
const theme = createTheme({
direction: 'rtl',
});
3. Configure RTL style plugin
Install the @mui/stylis-plugin-rtl using one of the commands below:
npm install stylis @mui/stylis-plugin-rtl
pnpm add stylis @mui/stylis-plugin-rtl
yarn add stylis @mui/stylis-plugin-rtl
With Emotion
If you're using Emotion, use the CacheProvider to create a new cache instance that uses rtlPlugin from @mui/stylis-plugin-rtl and add that to the top of your application tree:
import { CacheProvider } from '@emotion/react';
import createCache from '@emotion/cache';
import { prefixer } from 'stylis';
import rtlPlugin from '@mui/stylis-plugin-rtl';
// Create rtl cache
const rtlCache = createCache({
key: 'muirtl',
stylisPlugins: [prefixer, rtlPlugin],
});
function Rtl(props) {
return <CacheProvider value={rtlCache}>{props.children}</CacheProvider>;
}
With styled-components
If you're using styled-components, use the StyleSheetManager and provide rtlPlugin to the stylisPlugins property:
import { StyleSheetManager } from 'styled-components';
import rtlPlugin from '@mui/stylis-plugin-rtl';
function Rtl(props) {
return (
<StyleSheetManager stylisPlugins={[rtlPlugin]}>
{props.children}
</StyleSheetManager>
);
}
Opting out of RTL locally
To turn off RTL on specific components, use the template literal syntax and add the /* @noflip */ directive:
const LeftToRightTextInRtlApp = styled('div')`
/* @noflip */
text-align: left;
`;
{{"demo": "RtlOptOut.js"}}