Skip to content

Commit ae638d2

Browse files
erwanMarmelaberwanMarmelab
committed
document HorizontalMenu
1 parent 072a7c5 commit ae638d2

File tree

2 files changed

+222
-0
lines changed

2 files changed

+222
-0
lines changed

‎docs/HorizontalMenu.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
---
2+
layout: default
3+
title: "HorizontalMenu"
4+
---
5+
6+
# `<HorizontalMenu>`
7+
8+
A horizontal menu component, alternative to react-admin's `<Menu>`, to be used in the AppBar of the `<ContainerLayout>`.
9+
10+
![Container layout](./img/container-layout.png)
11+
12+
## Usage
13+
14+
Create a menu component based on `<HorizontalMenu>` and `<HorizontalMenu.Item>` (or `<HorizontalMenu.DashboardItem>`) children. Each child should have a `value` corresponding to the [application location](https://react-admin-ee.marmelab.com/documentation/ra-navigation#concepts) of the target, and can have a `to` prop corresponding to the target location if different from the app location.
15+
16+
```jsx
17+
import { HorizontalMenu } from '@react-admin/ra-navigation';
18+
19+
export const Menu = () => (
20+
<HorizontalMenu>
21+
<HorizontalMenu.DashboardItem label="Dashboard" value="" />
22+
<HorizontalMenu.Item label="Songs" to="/songs" value="songs" />
23+
<HorizontalMenu.Item label="Artists" to="/artists" value="artists" />
24+
</HorizontalMenu>
25+
);
26+
```
27+
28+
Then pass it to the `<ContainerLayout>`:
29+
30+
```jsx
31+
import { Admin, Resource } from 'react-admin';
32+
import { ContainerLayout } from '@react-admin/ra-navigation';
33+
34+
import { Menu } from './Menu';
35+
36+
const MyLayout = ({ children }) => (
37+
<ContainerLayout menu={<Menu />}>
38+
{children}
39+
</ContainerLayout>
40+
);
41+
42+
const App = () => (
43+
<Admin dataProvider={dataProvider} layout={MyLayout}>
44+
...
45+
</Admin>
46+
);
47+
```
48+
49+
## Prop
50+
51+
| Prop | Required | Type | Default | Description |
52+
| -------------- | -------- | --------- | ----------- | ---------------------------------------------------------------------------------------- |
53+
| `hasDashboard` | Optional | Boolean | | Display an `<HorizontalMenu.DashboardItem>` with your resources if no children specified |
54+
55+
It also accept the props of [MUI Tabs](https://mui.com/material-ui/api/tabs/#props).
56+
57+
## `hasDashboard`
58+
59+
When you're using `<HorizontalMenu>` without any child, it detects your resources and adds dedicated `<HorizontalMenu.Item>` components for you. You can specify that you want a `<HorizontalMenu.DashboardItem>` with it thanks to the `hasDashboard` prop.
60+
61+
```tsx
62+
import { ContainerLayout, HorizontalMenu } from '@react-admin/ra-navigation';
63+
64+
const MyLayout = ({ children }) => (
65+
<ContainerLayout menu={<HorizontalMenu hasDashboard />}>
66+
{children}
67+
</ContainerLayout>
68+
);
69+
```
70+
71+
## `<HorizontalMenu.Item>`
72+
73+
An item for the `<HorizontalMenu>` component. Used to define access to a resource or a custom route.
74+
75+
```tsx
76+
<HorizontalMenu>
77+
<HorizontalMenu.DashboardItem label="Home" />
78+
<HorizontalMenu.Item label="Artists" to="/artists" value="artists" />
79+
<HorizontalMenu.Item label="Songs" to="/songs" value="songs" />
80+
<HorizontalMenu.Item label="Labels" to="/labels" value="labels" />
81+
</HorizontalMenu>
82+
```
83+
84+
### Props
85+
86+
| Prop | Required | Type | Default | Description |
87+
| --------------- | -------- | --------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
88+
| `value` | Required | string | | The value of the Tab and the default route to use if no `to` is provided |
89+
| `label` | Optional | string | | The text to display |
90+
| `to` | Optional | string | | The route to which the item redirects |
91+
| `TabProps` | Optional | [TabProps](https://mui.com/material-ui/api/tabs/#props) | | Additional props of the Tab |
92+
| `MenuProps` | Optional | [MenuProps](https://mui.com/material-ui/api/menu/#props) | | Additional props of the Menu (`HorizontalMenu.Item` with children) |
93+
| `MenuItemProps` | Optional | [MenuItemProps](https://mui.com/material-ui/api/menu-item/#props) | | Additional props of the MenuItem (children of a `HorizontalMenu.Item`) |
94+
95+
### `value`
96+
97+
The `value` passed to the [MUI `Tab`](https://mui.com/material-ui/react-tabs/):
98+
99+
```tsx
100+
<HorizontalMenu>
101+
<HorizontalMenu.Item value="artists" />
102+
<HorizontalMenu.Item value="songs" />
103+
</HorizontalMenu>
104+
```
105+
106+
### `label`
107+
108+
You can customize the label by setting the `label` prop. It is inferred from the `value` prop by default.
109+
110+
`<HorizontalMenu.Item>` uses the i18n layer, so you can translate the label. Check [the Translation chapter](./TranslationTranslating.md) for more information.
111+
112+
```tsx
113+
<HorizontalMenu>
114+
<HorizontalMenu.Item label="Artists" value="artists" />
115+
<HorizontalMenu.Item label="ra.custom.path.resource.song" value="songs" />
116+
</HorizontalMenu>
117+
```
118+
119+
### `to`
120+
121+
You can customize the link of your resource by setting the `to` prop. It is inferred from the `value` prop by default as ``/${value}``.
122+
123+
```tsx
124+
<HorizontalMenu>
125+
<HorizontalMenu.Item to="/artists" value="artists" />
126+
<HorizontalMenu.Item to="/musics" value="songs" />
127+
</HorizontalMenu>
128+
```
129+
130+
### `TabProps`
131+
132+
Additional props passed to the [Tab](https://mui.com/material-ui/api/tabs/#props).
133+
134+
{% raw %}
135+
136+
```tsx
137+
import { HorizontalMenu } from '@react-admin/ra-navigation';
138+
import MusicNoteIcon from '@mui/icons-material/MusicNote';
139+
140+
const Menu = () => (
141+
<HorizontalMenu>
142+
<HorizontalMenu.Item
143+
value="songs"
144+
TabProps={{ icon: <MusicNoteIcon />, iconPosition: 'start' }}
145+
/>
146+
</HorizontalMenu>
147+
);
148+
```
149+
150+
{% endraw %}
151+
152+
### `MenuProps`
153+
154+
Additional props passed to the [Menu](https://mui.com/material-ui/api/menu/#props) (item displayed if it has children).
155+
156+
{% raw %}
157+
158+
```tsx
159+
<HorizontalMenu>
160+
<HorizontalMenu.Item
161+
value="songs"
162+
MenuProps={{ open: true, autoFocus: true }}
163+
>
164+
<HorizontalMenu.Item value="albums" />
165+
<HorizontalMenu.Item value="singles" />
166+
</HorizontalMenu.Item>
167+
</HorizontalMenu>
168+
```
169+
170+
{% endraw %}
171+
172+
### `MenuItemProps`
173+
174+
Additional props passed to the [MenuItem](https://mui.com/material-ui/api/menu-item/#props) (item displayed in a sub-menu).
175+
176+
{% raw %}
177+
178+
```tsx
179+
<HorizontalMenu>
180+
<HorizontalMenu.Item value="songs">
181+
<HorizontalMenu.Item
182+
value="albums"
183+
MenuItemProps={{
184+
divider: true,
185+
selected: isSelected(),
186+
}}
187+
/>
188+
<HorizontalMenu.Item value="singles" />
189+
</HorizontalMenu.Item>
190+
</HorizontalMenu>
191+
```
192+
193+
{% endraw %}
194+
195+
### Adding Sub-Menus
196+
197+
<video controls autoplay playsinline muted loop>
198+
<source src="https://react-admin-ee.marmelab.com/assets/horizontal-menu-submenu.mp4" type="video/mp4"/>
199+
Your browser does not support the video tag.
200+
</video>
201+
202+
`<HorizontalMenu.Item>` creates a menu item for a given path. But you can also add `<HorizontalMenu.Item>` components as a child to create a submenu.
203+
204+
```jsx
205+
<HorizontalMenu>
206+
<HorizontalMenu.DashboardItem label="Home" />
207+
<HorizontalMenu.Item label="artists" to="/artists" value="artists" />
208+
<HorizontalMenu.Item label="Business" value="business">
209+
<HorizontalMenu.Item label="Producers" to="/producers" value="producers" />
210+
<HorizontalMenu.Item label="Label" to="/label" value="label" />
211+
</HorizontalMenu.Item>
212+
<HorizontalMenu.Item label="songs" to="/songs" value="songs" />
213+
</HorizontalMenu>
214+
```
215+
216+
## `<HorizontalMenu.DashboardItem>`
217+
218+
This component adds a menu item that redirects to the `/` route. It accepts the same props as [`<HorizontalMenu.Item>`](#horizontalmenuitem).
219+
220+
```tsx
221+
<HorizontalMenu.DashboardItem value="" />
222+
```

‎docs/img/container-layout.png‎

83.6 KB
Loading

0 commit comments

Comments
 (0)