Skip to content

Commit bd26e2a

Browse files
mmalerbajelbourn
mmalerba
authored and
jelbourn
committed
docs(sidenav): update docs and add examples (#7775)
1 parent 70aa3c2 commit bd26e2a

30 files changed

+575
-328
lines changed

‎src/lib/sidenav/README.md‎

Lines changed: 1 addition & 166 deletions
Original file line numberDiff line numberDiff line change
@@ -1,166 +1 @@
1-
**NOTE: The <code>mat-sidenav-layout</code> element is deprecated. <code>mat-sidenav-container</code>
2-
should be used instead.**
3-
4-
5-
# MatSidenav
6-
7-
MatSidenav is the side navigation component for Angular Material. It is composed of two components: `<mat-sidenav-container>` and `<mat-sidenav>`.
8-
9-
## Screenshots
10-
11-
<img src="https://material.angularjs.org/material2_assets/sidenav-example.png">
12-
13-
14-
## `<mat-sidenav-container>`
15-
16-
The parent component. Contains the code necessary to coordinate one or two sidenav and the backdrop.
17-
18-
## `<mat-sidenav>`
19-
20-
The sidenav panel.
21-
22-
### Bound Properties
23-
24-
| Name | Type | Description |
25-
| --- | --- | --- |
26-
| `position` | `"start"\|"end"` | The position of this sidenav. In LTR direction, `"start"` will be shown on the left, `"end"` on the right. In RTL, it is reversed. `"start"` is used by default. If there is more than 1 sidenav on either side the container will be considered invalid and none of the sidenavs will be visible or toggleable until the container is valid again. |
27-
| `mode` | `"over"\|"push"\|"side"` | The mode or styling of the sidenav, default being `"over"`. With `"over"` the sidenav will appear above the content, and a backdrop will be shown. With `"push"` the sidenav will push the content of the `<mat-sidenav-container>` to the side, and show a backdrop over it. `"side"` will resize the content and keep the sidenav opened. Clicking the backdrop will close sidenavs that do not have `mode="side"`. |
28-
| `opened` | `boolean` | Whether or not the sidenav is opened. Use this binding to open/close the sidenav. |
29-
30-
### Events
31-
32-
| Name | Description |
33-
| --- | --- |
34-
| `open-start` | Emitted when the sidenav is starting opening. This should only be used to coordinate animations. |
35-
| `close-start` | Emitted when the sidenav is starting closing. This should only be used to coordinate animations. |
36-
| `open` | Emitted when the sidenav is done opening. Use this for, e.g., setting focus on controls or updating state. |
37-
| `close` | Emitted when the sidenav is done closing. |
38-
39-
### Methods
40-
41-
| Signature | Description |
42-
| --- | --- |
43-
| `open(): Promise<void>` | Open the sidenav. Equivalent to `opened = true`. Returns a promise that will resolve when the animation completes, or be rejected if the animation was cancelled. |
44-
| `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. |
45-
| `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. |
46-
47-
### Notes
48-
49-
The `<mat-sidenav>` will resize based on its content. You can also set its width in CSS, like so:
50-
51-
```css
52-
mat-sidenav {
53-
width: 200px;
54-
}
55-
```
56-
57-
Try to avoid percent based width as `resize` events are not (yet) supported.
58-
59-
## Examples
60-
61-
Here's a simple example of using the sidenav:
62-
63-
```html
64-
<app>
65-
<mat-sidenav-container>
66-
<mat-sidenav #start (open)="closeStartButton.focus()">
67-
Start Sidenav.
68-
<br>
69-
<button mat-button #closeStartButton (click)="start.close()">Close</button>
70-
</mat-sidenav>
71-
<mat-sidenav #end position="end">
72-
End Sidenav.
73-
<button mat-button (click)="end.close()">Close</button>
74-
</mat-sidenav>
75-
76-
My regular content. This will be moved into the proper DOM at runtime.
77-
<button mat-button (click)="start.open()">Open start sidenav</button>
78-
<button mat-button (click)="end.open()">Open end sidenav</button>
79-
80-
</mat-sidenav-container>
81-
</app>
82-
```
83-
84-
For a fullscreen sidenav, the recommended approach is set up the DOM such that the
85-
`mat-sidenav-container` can naturally take up the full space:
86-
87-
```html
88-
<app>
89-
<mat-sidenav-container>
90-
<mat-sidenav mode="side" opened="true">Drawer content</mat-sidenav>
91-
<div class="my-content">Main content</div>
92-
</mat-sidenav-container>
93-
</app>
94-
```
95-
```css
96-
html, body, material-app, mat-sidenav-container, .my-content {
97-
margin: 0;
98-
width: 100%;
99-
height: 100%;
100-
}
101-
```
102-
103-
For a sidenav with a FAB (or other floating element), the recommended approach is to place the FAB
104-
outside of the scrollable region and absolutely position it.
105-
106-
```html
107-
<app>
108-
<mat-sidenav-container class="my-container">
109-
<mat-sidenav mode="side" opened="true">
110-
<button mat-mini-fab class="my-fab">
111-
<mat-icon>add</mat-icon>
112-
</button>
113-
<div class="my-scrolling-content">
114-
Lorem ipsum dolor sit amet, pede a libero aenean phasellus, lectus metus sint ut risus,
115-
fusce vel in pellentesque. Nisl rutrum etiam morbi consectetuer tempor magna, aenean nullam
116-
nunc id, neque vivamus interdum sociis nulla scelerisque sem, dolor id wisi turpis magna
117-
aliquam magna. Risus accumsan hac eget etiam donec sed, senectus erat mattis quam, tempor
118-
vel urna occaecat cras, metus urna augue nec at. Et morbi amet dui praesent, nec eu at,
119-
ligula ipsum dui sollicitudin, quis nisl massa viverra ligula, mauris fermentum orci arcu
120-
enim fringilla. Arcu erat nulla in aenean lacinia ullamcorper, urna ante nam et sagittis,
121-
tristique vehicula nibh ipsum vivamus, proin proin. Porta commodo nibh quis libero amet.
122-
Taciti dui, sapien consectetuer.
123-
</div>
124-
</mat-sidenav>
125-
<button mat-mini-fab class="my-fab">
126-
<mat-icon>add</mat-icon>
127-
</button>
128-
<div class="my-scrolling-content">
129-
Lorem ipsum dolor sit amet, pede a libero aenean phasellus, lectus metus sint ut risus, fusce
130-
vel in pellentesque. Nisl rutrum etiam morbi consectetuer tempor magna, aenean nullam nunc id,
131-
neque vivamus interdum sociis nulla scelerisque sem, dolor id wisi turpis magna aliquam magna.
132-
Risus accumsan hac eget etiam donec sed, senectus erat mattis quam, tempor vel urna occaecat
133-
cras, metus urna augue nec at. Et morbi amet dui praesent, nec eu at, ligula ipsum dui
134-
sollicitudin, quis nisl massa viverra ligula, mauris fermentum orci arcu enim fringilla. Arcu
135-
erat nulla in aenean lacinia ullamcorper, urna ante nam et sagittis, tristique vehicula nibh
136-
ipsum vivamus, proin proin. Porta commodo nibh quis libero amet. Taciti dui, sapien
137-
consectetuer.
138-
</div>
139-
</mat-sidenav-container>
140-
</app>
141-
```
142-
```css
143-
.my-container {
144-
width: 500px;
145-
height: 300px;
146-
}
147-
148-
.my-container .mat-sidenav {
149-
max-width: 200px;
150-
}
151-
152-
.my-container .mat-sidenav-content,
153-
.my-container mat-sidenav {
154-
display: flex;
155-
}
156-
157-
.my-scrolling-content {
158-
overflow: auto;
159-
}
160-
161-
button.my-fab {
162-
position: absolute;
163-
right: 20px;
164-
bottom: 10px;
165-
}
166-
```
1+
Please see the official documentation at https://material.angular.io/components/component/sidenav

0 commit comments

Comments
 (0)