0
# Layout & Navigation
1

2
React Admin provides a comprehensive layout system with navigation components, application structure, and customizable UI elements. The layout system includes the app bar, sidebar navigation, menu system, and responsive design capabilities.
3

4
## Layout Component
5

6
The main `<Layout>` component defines the overall application structure and shell.
7

8
```typescript { .api }
9
import { Layout } from 'react-admin';
10

11
interface LayoutProps {
12
  appBar?: React.ComponentType<AppBarProps>;
13
  sidebar?: React.ComponentType<SidebarProps>;
14
  menu?: React.ComponentType<MenuProps>;
15
  error?: React.ComponentType;
16
  className?: string;
17
  sx?: any;
18
  children: React.ReactNode;
19
}
20

21
const Layout: React.FC<LayoutProps>;
22
```
23

24
### Custom Layout Example
25

26
```typescript
27
import { Layout, CheckForApplicationUpdate } from 'react-admin';
28
import { MyAppBar } from './MyAppBar';
29
import { MySidebar } from './MySidebar';
30

31
const MyLayout = ({ children, ...props }) => (
32
  <>
33
    <Layout
34
      {...props}
35
      appBar={MyAppBar}
36
      sidebar={MySidebar}
37
    >
38
      {children}
39
    </Layout>
40
    <CheckForApplicationUpdate />
41
  </>
42
);
43

44
// Usage in Admin
45
<Admin layout={MyLayout} dataProvider={dataProvider}>
46
  <Resource name="posts" list={PostList} />
47
</Admin>
48
```
49

50
## AppBar Component
51

52
The application bar provides the top navigation area with title, user menu, and actions.
53

54
```typescript { .api }
55
import { AppBar } from 'react-admin';
56

57
interface AppBarProps {
58
  alwaysOn?: boolean;
59
  className?: string;
60
  color?: 'default' | 'inherit' | 'primary' | 'secondary' | 'transparent';
61
  elevation?: number;
62
  position?: 'fixed' | 'absolute' | 'sticky' | 'static' | 'relative';
63
  title?: string | React.ReactElement;
64
  titleComponent?: React.ComponentType;
65
  toolbar?: React.ReactElement;
66
  userMenu?: React.ReactElement | false;
67
  sx?: any;
68
  children?: React.ReactNode;
69
}
70

71
const AppBar: React.FC<AppBarProps>;
72
```
73

74
### Custom AppBar Example
75

76
```typescript
77
import { AppBar, TitlePortal, RefreshIconButton, ToggleThemeButton } from 'react-admin';
78
import { Box, Typography } from '@mui/material';
79

80
const MyAppBar = () => (
81
  <AppBar
82
    sx={{
83
      '& .RaAppBar-title': {
84
        flex: 1,
85
        textOverflow: 'ellipsis',
86
        whiteSpace: 'nowrap',
87
        overflow: 'hidden',
88
      },
89
    }}
90
  >
91
    <TitlePortal />
92
    <Box flex="1" />
93
    <RefreshIconButton />
94
    <ToggleThemeButton />
95
  </AppBar>
96
);
97
```
98

99
## Sidebar Component
100

101
The sidebar contains navigation menus and can be collapsed/expanded.
102

103
```typescript { .api }
104
import { Sidebar } from 'react-admin';
105

106
interface SidebarProps {
107
  children?: React.ReactNode;
108
  className?: string;
109
  closedSize?: number;
110
  size?: number;
111
  sx?: any;
112
}
113

114
const Sidebar: React.FC<SidebarProps>;
115
```
116

117
### Custom Sidebar Example
118

119
```typescript
120
import { Sidebar, Menu, MenuItemLink, DashboardMenuItem } from 'react-admin';
121
import { Card, CardContent } from '@mui/material';
122
import LabelIcon from '@mui/icons-material/Label';
123

124
const MySidebar = () => (
125
  <Sidebar>
126
    <Menu>
127
      <DashboardMenuItem />
128
      <MenuItemLink
129
        to="/posts"
130
        state={{ _scrollToTop: true }}
131
        primaryText="Posts"
132
        leftIcon={<LabelIcon />}
133
      />
134
      <MenuItemLink
135
        to="/users"
136
        state={{ _scrollToTop: true }}
137
        primaryText="Users"
138
        leftIcon={<LabelIcon />}
139
      />
140
    </Menu>
141
    
142
    <Card sx={{ margin: 1 }}>
143
      <CardContent>
144
        <h4>Quick Stats</h4>
145
        <p>Posts: 142</p>
146
        <p>Users: 23</p>
147
      </CardContent>
148
    </Card>
149
  </Sidebar>
150
);
151
```
152

153
## Menu Components
154

155
### Menu
156

157
The main navigation menu component.
158

159
```typescript { .api }
160
import { Menu } from 'react-admin';
161

162
interface MenuProps {
163
  className?: string;
164
  dense?: boolean;
165
  hasDashboard?: boolean;
166
  children?: React.ReactNode;
167
  sx?: any;
168
}
169

170
const Menu: React.FC<MenuProps>;
171
```
172

173
### MenuItemLink
174

175
Individual menu item for navigation.
176

177
```typescript { .api }
178
import { MenuItemLink } from 'react-admin';
179

180
interface MenuItemLinkProps {
181
  to: string;
182
  primaryText?: string;
183
  leftIcon?: React.ReactElement;
184
  rightIcon?: React.ReactElement;
185
  onClick?: () => void;
186
  sidebarIsOpen?: boolean;
187
  dense?: boolean;
188
  className?: string;
189
  sx?: any;
190
  state?: any;
191
}
192

193
const MenuItemLink: React.FC<MenuItemLinkProps>;
194
```
195

196
### DashboardMenuItem
197

198
Pre-configured menu item for the dashboard.
199

200
```typescript { .api }
201
import { DashboardMenuItem } from 'react-admin';
202

203
interface DashboardMenuItemProps {
204
  className?: string;
205
  leftIcon?: React.ReactElement;
206
  primaryText?: string;
207
  sidebarIsOpen?: boolean;
208
  sx?: any;
209
  to?: string;
210
}
211

212
const DashboardMenuItem: React.FC<DashboardMenuItemProps>;
213
```
214

215
### ResourceMenuItem & ResourceMenuItems
216

217
Menu items for resources.
218

219
```typescript { .api }
220
import { ResourceMenuItem, ResourceMenuItems } from 'react-admin';
221

222
interface ResourceMenuItemProps {
223
  name: string;
224
  className?: string;
225
  leftIcon?: React.ReactElement;
226
  primaryText?: string;
227
  sidebarIsOpen?: boolean;
228
  sx?: any;
229
}
230

231
const ResourceMenuItem: React.FC<ResourceMenuItemProps>;
232
const ResourceMenuItems: React.FC<{ className?: string; sx?: any }>;
233
```
234

235
### Menu Examples
236

237
```typescript
238
import { Menu, MenuItemLink, DashboardMenuItem, ResourceMenuItems } from 'react-admin';
239
import { Dashboard, People, Article, Settings, Analytics } from '@mui/icons-material';
240

241
const CustomMenu = () => (
242
  <Menu>
243
    <DashboardMenuItem leftIcon={<Dashboard />} />
244
    <ResourceMenuItems />
245
    
246
    <MenuItemLink
247
      to="/analytics"
248
      primaryText="Analytics"
249
      leftIcon={<Analytics />}
250
    />
251
    
252
    <MenuItemLink
253
      to="/settings"
254
      primaryText="Settings"
255
      leftIcon={<Settings />}
256
    />
257
  </Menu>
258
);
259
```
260

261
## Title and Page Management
262

263
### Title Component
264

265
Manages page titles and breadcrumbs.
266

267
```typescript { .api }
268
import { Title } from 'react-admin';
269

270
interface TitleProps {
271
  defaultTitle?: string;
272
  record?: RaRecord;
273
  title?: string | React.ReactElement;
274
  className?: string;
275
  sx?: any;
276
}
277

278
const Title: React.FC<TitleProps>;
279
```
280

281
### TitlePortal
282

283
Portal for rendering dynamic titles in the AppBar.
284

285
```typescript { .api }
286
import { TitlePortal } from 'react-admin';
287

288
const TitlePortal: React.FC;
289
```
290

291
### PageTitleConfigurable
292

293
Configurable page title component.
294

295
```typescript { .api }
296
import { PageTitleConfigurable } from 'react-admin';
297

298
const PageTitleConfigurable: React.FC<{ preferenceKey?: string }>;
299
```
300

301
## Navigation Hooks
302

303
### useSidebarState
304

305
Manage sidebar open/closed state.
306

307
```typescript { .api }
308
import { useSidebarState } from 'react-admin';
309

310
const useSidebarState: () => [boolean, () => void];
311
```
312

313
#### Usage Example
314

315
```typescript
316
import { useSidebarState } from 'react-admin';
317
import { IconButton } from '@mui/material';
318
import { Menu as MenuIcon } from '@mui/icons-material';
319

320
const SidebarToggle = () => {
321
  const [sidebarIsOpen, setSidebarVisibility] = useSidebarState();
322
  
323
  return (
324
    <IconButton onClick={() => setSidebarVisibility()}>
325
      <MenuIcon />
326
    </IconButton>
327
  );
328
};
329
```
330

331
### useBasename
332

333
Access the application's base URL.
334

335
```typescript { .api }
336
import { useBasename } from 'react-admin';
337

338
const useBasename: () => string;
339
```
340

341
### useCreatePath
342

343
Create navigation paths for resources.
344

345
```typescript { .api }
346
import { useCreatePath } from 'react-admin';
347

348
const useCreatePath: () => (params: CreatePathParams) => string;
349

350
interface CreatePathParams {
351
  type: 'list' | 'create' | 'edit' | 'show';
352
  resource: string;
353
  id?: Identifier;
354
}
355
```
356

357
### useRedirect
358

359
Programmatic navigation and redirection.
360

361
```typescript { .api }
362
import { useRedirect } from 'react-admin';
363

364
type RedirectFunction = (
365
  page: string,
366
  resource?: string,
367
  id?: Identifier,
368
  data?: any,
369
  state?: any
370
) => void;
371

372
const useRedirect: () => RedirectFunction;
373
```
374

375
#### Usage Examples
376

377
```typescript
378
import { useRedirect } from 'react-admin';
379

380
const MyComponent = () => {
381
  const redirect = useRedirect();
382
  
383
  const handleSuccess = (data) => {
384
    // Redirect to show page
385
    redirect('show', 'posts', data.id);
386
    
387
    // Redirect to list
388
    redirect('list', 'posts');
389
    
390
    // Redirect to external URL
391
    redirect('/dashboard');
392
  };
393
  
394
  return <button onClick={handleSuccess}>Save and View</button>;
395
};
396
```
397

398
## TopToolbar
399

400
Container for action buttons at the top of views.
401

402
```typescript { .api }
403
import { TopToolbar } from 'react-admin';
404

405
interface TopToolbarProps {
406
  className?: string;
407
  sx?: any;
408
  children?: React.ReactNode;
409
}
410

411
const TopToolbar: React.FC<TopToolbarProps>;
412
```
413

414
### TopToolbar Example
415

416
```typescript
417
import { TopToolbar, CreateButton, ExportButton, FilterButton } from 'react-admin';
418

419
const ListActions = () => (
420
  <TopToolbar>
421
    <FilterButton />
422
    <CreateButton />
423
    <ExportButton />
424
  </TopToolbar>
425
);
426

427
const PostList = () => (
428
  <List actions={<ListActions />}>
429
    <Datagrid>
430
      <TextField source="title" />
431
    </Datagrid>
432
  </List>
433
);
434
```
435

436
## User Menu
437

438
### UserMenu
439

440
Dropdown menu for user-related actions.
441

442
```typescript { .api }
443
import { UserMenu } from 'react-admin';
444

445
interface UserMenuProps {
446
  children?: React.ReactNode;
447
  className?: string;
448
  label?: string;
449
  icon?: React.ReactElement;
450
  sx?: any;
451
}
452

453
const UserMenu: React.FC<UserMenuProps>;
454
```
455

456
### useUserMenu
457

458
Hook for accessing user menu functionality.
459

460
```typescript { .api }
461
import { useUserMenu } from 'react-admin';
462

463
const useUserMenu: () => {
464
  isOpen: boolean;
465
  open: (event: React.MouseEvent) => void;
466
  close: () => void;
467
  anchorEl: HTMLElement | null;
468
};
469
```
470

471
### Custom User Menu Example
472

473
```typescript
474
import { UserMenu, MenuItemLink, Logout } from 'react-admin';
475
import { MenuItem } from '@mui/material';
476
import { Settings, Person } from '@mui/icons-material';
477

478
const CustomUserMenu = () => (
479
  <UserMenu>
480
    <MenuItemLink
481
      to="/profile"
482
      primaryText="Profile"
483
      leftIcon={<Person />}
484
    />
485
    <MenuItemLink
486
      to="/settings"
487
      primaryText="Settings"  
488
      leftIcon={<Settings />}
489
    />
490
    <Logout />
491
  </UserMenu>
492
);
493
```
494

495
## Loading and Error States
496

497
### Loading
498

499
Loading indicator component.
500

501
```typescript { .api }
502
import { Loading } from 'react-admin';
503

504
interface LoadingProps {
505
  className?: string;
506
  sx?: any;
507
  loadingPrimary?: string;
508
  loadingSecondary?: string;
509
}
510

511
const Loading: React.FC<LoadingProps>;
512
```
513

514
### LoadingIndicator
515

516
Global loading indicator.
517

518
```typescript { .api }
519
import { LoadingIndicator } from 'react-admin';
520

521
const LoadingIndicator: React.FC<{ className?: string; sx?: any }>;
522
```
523

524
### Error Boundary
525

526
Error handling and display.
527

528
```typescript { .api }
529
import { Error } from 'react-admin';
530

531
interface ErrorProps {
532
  error?: any;
533
  errorInfo?: any;
534
  title?: string;
535
  className?: string;
536
  sx?: any;
537
}
538

539
const Error: React.FC<ErrorProps>;
540
```
541

542
### NotFound
543

544
404 error page component.
545

546
```typescript { .api }
547
import { NotFound } from 'react-admin';
548

549
interface NotFoundProps {
550
  className?: string;
551
  sx?: any;
552
  title?: string;
553
}
554

555
const NotFound: React.FC<NotFoundProps>;
556
```
557

558
## Responsive Design
559

560
### DeviceTestWrapper
561

562
Component for testing responsive behavior.
563

564
```typescript { .api }
565
import { DeviceTestWrapper } from 'react-admin';
566

567
interface DeviceTestWrapperProps {
568
  width?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
569
  children: React.ReactNode;
570
}
571

572
const DeviceTestWrapper: React.FC<DeviceTestWrapperProps>;
573
```
574

575
### useMediaQuery
576

577
Hook for responsive design (from Material-UI).
578

579
```typescript
580
import { useMediaQuery, useTheme } from '@mui/material';
581

582
const MyResponsiveComponent = () => {
583
  const theme = useTheme();
584
  const isSmall = useMediaQuery(theme.breakpoints.down('sm'));
585
  
586
  return (
587
    <div>
588
      {isSmall ? (
589
        <SimplifiedView />
590
      ) : (
591
        <FullView />
592
      )}
593
    </div>
594
  );
595
};
596
```
597

598
## Advanced Layout Examples
599

600
### Multi-Level Menu
601

602
```typescript
603
import { Menu, MenuItemLink, Collapse, List, ListItem } from 'react-admin';
604
import { useState } from 'react';
605
import { ExpandLess, ExpandMore, Dashboard, Article, People } from '@mui/icons-material';
606

607
const MultiLevelMenu = () => {
608
  const [contentOpen, setContentOpen] = useState(false);
609
  
610
  return (
611
    <Menu>
612
      <DashboardMenuItem leftIcon={<Dashboard />} />
613
      
614
      <ListItem button onClick={() => setContentOpen(!contentOpen)}>
615
        <ListItemIcon><Article /></ListItemIcon>
616
        <ListItemText primary="Content" />
617
        {contentOpen ? <ExpandLess /> : <ExpandMore />}
618
      </ListItem>
619
      
620
      <Collapse in={contentOpen}>
621
        <List component="div" disablePadding>
622
          <MenuItemLink
623
            to="/posts"
624
            primaryText="Posts"
625
            sx={{ pl: 4 }}
626
          />
627
          <MenuItemLink
628
            to="/pages"
629
            primaryText="Pages"
630
            sx={{ pl: 4 }}
631
          />
632
        </List>
633
      </Collapse>
634
      
635
      <MenuItemLink
636
        to="/users"
637
        primaryText="Users"
638
        leftIcon={<People />}
639
      />
640
    </Menu>
641
  );
642
};
643
```
644

645
### Layout with Breadcrumbs
646

647
```typescript
648
import { Layout, Breadcrumbs } from 'react-admin';
649
import { useLocation, useParams } from 'react-router-dom';
650

651
const BreadcrumbLayout = ({ children, ...props }) => {
652
  const location = useLocation();
653
  const params = useParams();
654
  
655
  return (
656
    <Layout {...props}>
657
      <Breadcrumbs location={location} params={params} />
658
      {children}
659
    </Layout>
660
  );
661
};
662
```
663

664
### Contextual Sidebar
665

666
```typescript
667
import { Sidebar, useResourceContext, useGetOne } from 'react-admin';
668
import { Card, CardContent, List, ListItem } from '@mui/material';
669

670
const ContextualSidebar = () => {
671
  const resource = useResourceContext();
672
  
673
  if (resource === 'posts') {
674
    return <PostSidebar />;
675
  }
676
  
677
  if (resource === 'users') {
678
    return <UserSidebar />;
679
  }
680
  
681
  return <DefaultSidebar />;
682
};
683

684
const PostSidebar = () => (
685
  <Sidebar>
686
    <Card>
687
      <CardContent>
688
        <h3>Post Management</h3>
689
        <List>
690
          <ListItem>Drafts: 15</ListItem>
691
          <ListItem>Published: 142</ListItem>
692
          <ListItem>Archived: 8</ListItem>
693
        </List>
694
      </CardContent>
695
    </Card>
696
  </Sidebar>
697
);
698
```
699

700
### Mobile-Optimized Layout
701

702
```typescript
703
import { Layout, useMediaQuery } from 'react-admin';
704
import { useTheme } from '@mui/material';
705

706
const ResponsiveLayout = ({ children, ...props }) => {
707
  const theme = useTheme();
708
  const isSmall = useMediaQuery(theme.breakpoints.down('sm'));
709
  
710
  return (
711
    <Layout
712
      {...props}
713
      sidebar={isSmall ? undefined : props.sidebar}
714
      appBar={isSmall ? MobileAppBar : props.appBar}
715
    >
716
      {children}
717
    </Layout>
718
  );
719
};
720

721
const MobileAppBar = ({ ...props }) => (
722
  <AppBar {...props}>
723
    <SidebarToggleButton />
724
    <TitlePortal />
725
    <UserMenu />
726
  </AppBar>
727
);
728
```
729

730
### Dashboard Integration
731

732
```typescript
733
import { Admin, Resource, CustomRoutes } from 'react-admin';
734
import { Route } from 'react-router-dom';
735

736
const Dashboard = () => (
737
  <div>
738
    <h1>Welcome to Admin Dashboard</h1>
739
    <div style={{ display: 'flex', gap: 20 }}>
740
      <Card>
741
        <CardContent>
742
          <h3>Recent Posts</h3>
743
          <RecentPosts />
744
        </CardContent>
745
      </Card>
746
      
747
      <Card>
748
        <CardContent>
749
          <h3>User Activity</h3>
750
          <UserActivity />
751
        </CardContent>
752
      </Card>
753
    </div>
754
  </div>
755
);
756

757
const App = () => (
758
  <Admin 
759
    dataProvider={dataProvider}
760
    dashboard={Dashboard}
761
    layout={MyLayout}
762
  >
763
    <Resource name="posts" list={PostList} />
764
    <Resource name="users" list={UserList} />
765
    
766
    <CustomRoutes>
767
      <Route path="/analytics" element={<AnalyticsPage />} />
768
    </CustomRoutes>
769
  </Admin>
770
);
771
```
772

773
React Admin's layout and navigation system provides a flexible foundation for creating sophisticated admin interfaces with customizable navigation, responsive design, and comprehensive user experience features.