Skip to content

Commit 43f6f41

Browse files
mmalerbammalerba
committed
rewrite sidenav docs
1 parent f17cb99 commit 43f6f41

File tree

2 files changed

+139
-57
lines changed

2 files changed

+139
-57
lines changed

‎src/lib/sidenav/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ The sidenav panel.
4444
| `close(): Promise<void>` | Close the sidenav. Equivalent to `opened = false`. Returns a promise that will resolve when the animation completes, or be rejected if the animation was cancelled. |
4545
| `toggle(): Promise<void>` | Toggle the sidenav. This is equivalent to `opened = !opened`. Returns a promise that will resolve when the animation completes, or be rejected if the animation was cancelled. |
4646

47+
48+
49+
50+
4751
### Notes
4852

4953
The `<mat-sidenav>` will resize based on its content. You can also set its width in CSS, like so:

‎src/lib/sidenav/sidenav.md

Lines changed: 135 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,131 @@
1-
`<mat-sidenav>` is a panel that can be placed next to or above some primary content. A sidenav is
2-
typically used for navigation, but can contain any content.
1+
Angular Material provides two sets of components designed to add collapsible side content (often
2+
navigation, though it can be any content) alongside some primary content. These are the sidenav and
3+
drawer components.
34

4-
<!-- example(sidenav-overview) -->
5+
The sidenav components are designed to add side content to a fullscreen app. To set up a sidenav we
6+
use three components: `<mat-sidenav-container>` which acts as a structural container for our content
7+
and sidenav, `<mat-sidenav-content>` which represents the main content, and `<mat-sidenav>` which
8+
represents the added side content.
9+
10+
<!-- TODO(mmalerba): sidenav example -->
11+
12+
There are also drawer components, `<mat-drawer-container>`, `<mat-drawer-content>`, and
13+
`<mat-drawer>`, which are analogous to their sidenav equivalents. Rather than adding side content
14+
to the app as a whole, these are designed to add side content to a small section of your app. They
15+
support almost all of the same features, but do not support fixed positioning.
16+
17+
<!-- TODO(mmalerba): drawer example -->
18+
19+
### Specifying the main and side content
20+
21+
Both the main and side content should be placed inside of the `<mat-sidenav-container>`, content
22+
that you don't want to be affected by the sidenav, such as a header or footer, can be placed outside
23+
of the container.
24+
25+
The side content should be wrapped in a `<mat-sidenav>` element. The `position` property can be used
26+
to specify which end of the main content to place the side content on. `position` can be either
27+
`start` or `end` which places the side content on the left or right respectively in left-to-right
28+
languages. If the `position` is not set, the `start` end will be assumed. A
29+
`<mat-sidenav-container>` can have up to two `<mat-sidenav>` elements total, but only one for any
30+
given side.
31+
32+
The main content should be wrapped in a `<mat-sidenav-content>`. If no `<mat-sidenav-content>` is
33+
specified for a `<mat-sidenav-container>`, one will be created implicitly and all of the content
34+
inside the `<mat-sidenav-container>` other than the `<mat-sidenav>` elements will be placed inside
35+
of it.
36+
37+
The following are examples of valid sidenav layouts:
538

6-
The sidenav and its associated content live inside of an `<mat-sidenav-container>`:
739
```html
840
<mat-sidenav-container>
9-
<mat-sidenav>
10-
<!-- sidenav content -->
11-
</mat-sidenav>
41+
<mat-sidenav>Start</mat-sidenav>
42+
<mat-sidenav-content>Main</mat-sidenav-content>
43+
</mat-sidenav-container>
44+
```
1245

13-
<!-- primary content -->
46+
```html
47+
<mat-sidenav-container>
48+
<mat-sidenav>Start</mat-sidenav>
49+
<mat-sidenav position="end">End</mat-sidenav>
50+
<section>Main</section>
1451
</mat-sidenav-container>
1552
```
1653

17-
A sidenav container may contain one or two `<mat-sidenav>` elements. When there are two
18-
`<mat-sidenav>` elements, each must be placed on a different side of the container.
19-
See the section on positioning below.
54+
```html
55+
<mat-sidenav-container></mat-sidenav-container>
56+
```
2057

21-
### Sidenav mode
22-
The sidenav can render in one of three different ways based on the `mode` property.
58+
Anf these are examples of invalid sidenav layouts:
59+
60+
```html
61+
<mat-sidenav-container>
62+
<mat-sidenav>Start</mat-sidenav>
63+
<mat-sidenav position="start">Start 2</mat-sidenav>
64+
</mat-sidenav-container>
65+
```
66+
67+
```html
68+
<mat-sidenav-container>
69+
<mat-sidenav-content>Main</mat-sidenav-content>
70+
<mat-sidenav-content>Main 2</mat-sidenav-content>
71+
</mat-sidenav-container>
72+
```
73+
74+
```html
75+
<mat-sidenav-container></mat-sidenav-container>
76+
<mat-sidenav></mat-sidenav>
77+
```
2378

24-
| Mode | Description |
25-
|------|-------------------------------------------------------------------------------------------|
26-
| over | Sidenav floats _over_ the primary content, which is covered by a backdrop |
27-
| push | Sidenav _pushes_ the primary content out of its way, also covering it with a backdrop |
28-
| side | Sidenav appears _side-by-side_ with the primary content |
79+
These same rules all apply to the drawer components as well.
2980

30-
Using the `side` mode on mobile devices can affect the performance and is also not recommended by the
31-
[Material Design specification](https://material.io/guidelines/patterns/navigation-drawer.html#navigation-drawer-behavior).
81+
### Opening and closing a sidenav
3282

33-
### Positioning the sidenav
34-
The `position` property determines whether the sidenav appears at the `"start"` or `"end"` of the
35-
container. This is affected by the current text direction ("ltr" or "rtl"). By default, the sidenav
36-
appears at the start of the container.
83+
A `<mat-sidenav>` can be opened or closed using the `open()`, `close()` and `toggle()` methods. Each
84+
of these methods returns a `Promise<boolean>` that will be resolved with `true` when the sidenav
85+
finishes opening or `false` when it finishes closing.
3786

87+
The opened state can also be set via a property binding in the template using the `opened` property.
88+
The property supports 2-way binding.
3889

39-
### Sizing the sidenav
40-
The `<mat-sidenav>` will, by default, fit the size of its content. The width can be explicitly set
41-
via CSS:
90+
`<mat-sidenav>` also supports output properties for just open and just close events, The `(opened)`
91+
and `(closed)` properties respectively.
92+
93+
<!-- TODO(mmalerba): open/close example -->
94+
95+
All of these properties and methods work on `<mat-drawer>` as well.
96+
97+
### Changing the sidenav's behavior
98+
99+
The `<mat-sidenav>` can render in one of three different ways based on the `mode` property.
100+
101+
| Mode | Description |
102+
|--------|-----------------------------------------------------------------------------------------|
103+
| `over` | Sidenav floats _over_ the primary content, which is covered by a backdrop |
104+
| `push` | Sidenav _pushes_ the primary content out of its way, also covering it with a backdrop |
105+
| `side` | Sidenav appears _side-by-side_ with the main content, shrinking the main content's width to make space for the sidenav. |
106+
107+
If no `mode` is specified, `over` is used by default.
108+
109+
<!-- TODO(mmalerba): modes example -->
110+
111+
`<mat-drawer>` also supports all of these same modes.
112+
113+
### Disabling automatic close
114+
115+
Clicking on the backdrop or pressing the <kbd>Esc</kbd> key will normally close an open sidenav.
116+
However, this automatic closing behavior can be disabled by setting the `disableClose` property on
117+
the `<mat-sidenav>` or `<mat-drawer>` that you want to disable the behavior for.
118+
119+
Custom handling for <kbd>Esc</kbd> can be done by adding a keydown listener to the `<mat-sidenav>`.
120+
Custom handling for backdrop clicks can be done via the `(backdropClick)` output property on
121+
`<mat-sidenav-container>`.
122+
123+
<!-- TODO(mmalerba): autoclose example -->
124+
125+
### Setting the sidenav's size
126+
127+
The `<mat-sidenav>` and `<mat-drawer>` will, by default, fit the size of its content. The width can
128+
be explicitly set via CSS:
42129

43130
```css
44131
mat-sidenav {
@@ -48,37 +135,28 @@ mat-sidenav {
48135

49136
Try to avoid percent based width as `resize` events are not (yet) supported.
50137

51-
For a fullscreen sidenav, the recommended approach is set up the DOM such that the
52-
`<mat-sidenav-container>` can naturally take up the full space:
138+
### Fixed position sidenavs
53139

54-
```html
55-
<app>
56-
<mat-sidenav-container>
57-
<mat-sidenav mode="side" opened="true">Drawer content</mat-sidenav>
58-
<div class="my-content">Main content</div>
59-
</mat-sidenav-container>
60-
</app>
61-
```
62-
```css
63-
html, body, material-app, mat-sidenav-container, .my-content {
64-
margin: 0;
65-
width: 100%;
66-
height: 100%;
67-
}
68-
```
140+
For `<mat-sidenav>` only (not `<mat-drawer>`) fixed positioning is supported. It can be enabled by
141+
setting the `fixedInViewport` property. Additionally, top and bottom space can be set via the
142+
`fixedTopGap` and `fixedBottomGap`. These properties accept a pixel value amount of space to add at
143+
the top or bottom.
69144

70-
### FABs inside sidenav
71-
For a sidenav with a FAB (Floating Action Button) or other floating element, the recommended approach is to place the FAB
72-
outside of the scrollable region and absolutely position it.
145+
<!-- TODO(mmalerba): fixed example -->
73146

147+
### Common layout patterns
74148

75-
### Disabling closing of sidenav
76-
By default, sidenav can be closed either by clicking on the backdrop or by pressing <kbd>ESCAPE</kbd>.
77-
The `disableClose` attribute can be set on `mat-sidenav` to disable automatic closing when the backdrop
78-
is clicked or <kbd>ESCAPE</kbd> is pressed. To add custom logic on backdrop click, add a `(backdropClick)` listener to
79-
`mat-sidenav-container`. For custom <kbd>ESCAPE</kbd> logic, a standard `(keydown)` listener will suffice.
80-
```html
81-
<mat-sidenav-container (backdropClick)="customBackdropClickHandler()">
82-
<mat-sidenav disableClose (keydown)="customKeydownHandler($event)"></mat-sidenav>
83-
</mat-sidenav-container>
84-
```
149+
<!-- TODO(mmalerba): fill out -->
150+
151+
#### Full-height sidenav
152+
#### Sidenav under toolbar
153+
#### Mobile sidenav
154+
#### Responsive sidenav
155+
156+
### Accessibility
157+
158+
<!-- TODO(mmalerba): fill out -->
159+
160+
### Troubleshooting
161+
162+
<!-- TODO(mmalerba): fill out -->

0 commit comments

Comments
 (0)