Merge pull request #9171 from marmelab/title-portal-props

Add ability to customize the page title style

Author: adguernier

docs/AppBar.md

@@ -101,6 +101,17 @@ export const MyAppBar = () => (
 ![App bar with a settings button](./img/AppBar-children.png)
 
 **Tip**: Whats the `<TitlePortal>`? It's a placeholder for the page title, that components in the page can fill using [the `<Title>` component](./Title.md). `<Title>` uses a [React Portal](https://react.dev/reference/react-dom/createPortal) under the hood. `<TitlePortal>` takes all the available space in the app bar, so it "pushes" the following children to the right.
+
+**Tip**: `<TitlePortal>` renders a [Material-ui `<Typography>`](https://mui.com/material-ui/react-typography/) element that you can customize by passing your own props:
+
+```jsx
+export const MyAppBar = () => (
+    <AppBar>
+        <TitlePortal variant="body2" component="h3" />
+        <SettingsButton />
+    </AppBar>
+);
+```
 
 If you omit `<TitlePortal>`, `<AppBar>` will no longer display the page title. This can be done on purpose, e.g. if you want to render something completely different in the AppBar, like a company logo and a search engine:
 

docs/Layout.md

@@ -40,7 +40,7 @@ export const MyLayout = props => <Layout {...props} appBar={MyAppBar} />;
 
 Then pass this custom layout to the `<Admin>` component:
 
-Instead of the default layout, you can use your own component as the admin layout. Just use the layout prop of the <Admin> component:
+Instead of the default layout, you can use your own component as the admin layout. Just use the layout prop of the `<Admin>` component:
 
 ```jsx
 // in src/App.js
@@ -98,7 +98,7 @@ export const MyLayout = (props) => <Layout {...props} appBar={MyAppBar} />;
 
 You can use [react-admin's `<AppBar>` component](./AppBar.md) as a base for your custom app bar, or the component of your choice. 
 
-By default, react-admin's `<AppBar>` displays the page title. You can override this default by passing children to `<AppBar>` - they will replace the default title. And if you still want to include the page title, make sure you include an element with id `react-admin-title` in the top bar (this uses [React Portals](https://react.dev/reference/react-dom/createPortal)).
+By default, react-admin's `<AppBar>` displays the page title. You can override this default by passing children to `<AppBar>` - they will replace the default title. And if you still want to include the page title defined by each page, make sure you include the `<TitlePortal>` element (which uses [React Portals](https://react.dev/reference/react-dom/createPortal)).
 
 Here is a custom app bar component extending `<AppBar>` to include a company logo in the center of the page header:
 

docs/Title.md

@@ -24,7 +24,7 @@ const CustomPage = () => (
 );
 ```
 
-`<Title>` uses a [React Portal](https://react.dev/reference/react-dom/createPortal) to render the title outside of the current component. It works because the default [ `<AppBar>`](./AppBar.md) component contains a placeholder for the title called `<TitlePortal>`.
+`<Title>` uses a [React Portal](https://react.dev/reference/react-dom/createPortal) to render the title outside of the current component. It works because the default [`<AppBar>`](./AppBar.md) component contains a placeholder for the title called `<TitlePortal>`.
 
 CRUD page components ([`<List>`](./List.md), [`<Edit>`](./Edit.md), [`<Create>`](./Create.md), [`<Show>`](./Show.md)) already use a `<Title>` component. To set the page title for these components, use the `title` prop.
 

packages/ra-ui-materialui/src/layout/TitlePortal.stories.tsx

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import { MemoryRouter } from 'react-router-dom';
+
+import { TitlePortal } from './TitlePortal';
+import { Title } from './Title';
+
+export default {
+    title: 'ra-ui-materialui/layout/TitlePortal',
+};
+
+export const Basic = () => (
+    <MemoryRouter>
+        <TitlePortal />
+        <Title title="Hello, world" />
+    </MemoryRouter>
+);
+
+export const Props = () => (
+    <MemoryRouter>
+        <TitlePortal variant="body1" />
+        <Title title="Hello, world" />
+    </MemoryRouter>
+);
+
+export const Sx = () => (
+    <MemoryRouter>
+        <TitlePortal sx={{ color: 'primary.main' }} />
+        <Title title="Hello, world" />
+    </MemoryRouter>
+);

packages/ra-ui-materialui/src/layout/TitlePortal.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
-import { Typography } from '@mui/material';
+import { Typography, TypographyProps } from '@mui/material';
 
-export const TitlePortal = ({ className }: { className?: string }) => (
+export const TitlePortal = (props: TypographyProps) => (
     <Typography
         flex="1"
         textOverflow="ellipsis"
@@ -10,6 +10,6 @@ export const TitlePortal = ({ className }: { className?: string }) => (
         variant="h6"
         color="inherit"
         id="react-admin-title"
-        className={className}
+        {...props}
     />
 );