Skip to content

Commit 09b5bf4

Browse files
jelbournjelbourn
committed
docs(cdk/layout): better explain how layout breakpoints work
I'm copying the actual breakpoints here for reference because it's much easier to parse than looking at the archived Material Design site. I'm also working on a follow-up to add an overview example for `BreakpointObserver`. Fixes #11788
1 parent 298fed2 commit 09b5bf4

File tree

1 file changed

+46
-39
lines changed

1 file changed

+46
-39
lines changed

‎src/cdk/layout/layout.md

Lines changed: 46 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,24 @@ The `layout` package provides utilities to build responsive UIs that react to sc
22

33
### BreakpointObserver
44

5-
`BreakpointObserver` is a utility for evaluating media queries and reacting to changes in the results of those queries.
5+
A layout **breakpoint** is viewport size threshold at which a layout shift can occur. The viewport
6+
size ranges between breakpoints correspond to different standard screen sizes.
7+
8+
`BreakpointObserver` lets you evaluate media queries to determine the current screen size and
9+
react to changes when the viewport size crosses a breakpoint.
10+
11+
#### Check the current viewport size
12+
You can use the `isMatched` method to evaluate one or more media queries against the current
13+
viewport size.
614

7-
#### Evaluate against the current viewport
8-
The `isMatched` method is used to evaluate one or more media queries against the current viewport
9-
size.
1015
```ts
1116
const isSmallScreen = breakpointObserver.isMatched('(max-width: 599px)');
1217
```
1318

1419
#### React to changes to the viewport
15-
The `observe` method is used to get an observable stream that will emit whenever one of the given
16-
media queries would have a different result.
20+
You can use the `observe` method to get an observable stream that emits whenever the viewport size
21+
crosses a breakpoint.
22+
1723
```ts
1824
const layoutChanges = breakpointObserver.observe([
1925
'(orientation: portrait)',
@@ -25,45 +31,46 @@ layoutChanges.subscribe(result => {
2531
});
2632
```
2733

28-
#### Default breakpoints
29-
A set of default media queries are available corresponding to breakpoints for different device
30-
types.
34+
#### Predefined breakpoints
3135

32-
```ts
33-
import {BreakpointObserver, Breakpoints} from '@angular/cdk/layout';
36+
The built-in `Breakpoints` constant offers the following predefined breakpoints for convenience,
37+
[originally drawn from the Material Design
38+
specification](https://material.io/archive/guidelines/layout/responsive-ui.html).
3439

35-
@Component({...})
36-
class MyComponent {
37-
constructor(breakpointObserver: BreakpointObserver) {
38-
breakpointObserver.observe([
39-
Breakpoints.HandsetLandscape,
40-
Breakpoints.HandsetPortrait
41-
]).subscribe(result => {
42-
if (result.matches) {
43-
this.activateHandsetLayout();
44-
}
45-
});
46-
}
47-
}
48-
```
40+
| Breakpoint name | Media query |
41+
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
42+
| `XSmall` | `(max-width: 599.98px)` |
43+
| `Small` | `(min-width: 600px) and (max-width: 959.98px)` |
44+
| `Medium` | `(min-width: 960px) and (max-width: 1279.98px)` |
45+
| `Large` | `(min-width: 1280px) and (max-width: 1919.98px)` |
46+
| `XLarge` | `(min-width: 1920px)` |
47+
| `Handset` | `(max-width: 599.98px) and (orientation: portrait), (max-width: 959.98px) and (orientation: landscape)` |
48+
| `Tablet` | `(min-width: 600px) and (max-width: 839.98px) and (orientation: portrait), (min-width: 960px) and (max-width: 1279.98px) and (orientation: landscape)` |
49+
| `Web` | `(min-width: 840px) and (orientation: portrait), (min-width: 1280px) and (orientation: landscape)` |
50+
| `HandsetPortrait` | `(max-width: 599.98px) and (orientation: portrait)` |
51+
| `TabletPortrait` | `(min-width: 600px) and (max-width: 839.98px) and (orientation: portrait)` |
52+
| `WebPortrait` | `(min-width: 840px) and (orientation: portrait)` |
53+
| `HandsetLandscape` | `(max-width: 959.98px) and (orientation: landscape)` |
54+
| `TabletLandscape` | `(min-width: 960px) and (max-width: 1279.98px) and (orientation: landscape)` |
55+
| `WebLandscape` | `(min-width: 1280px) and (orientation: landscape)` |
4956

50-
The built-in breakpoints based on [Google's Material Design
51-
specification](https://material.io/design/layout/responsive-layout-grid.html#breakpoints).
52-
The available values are:
53-
* Handset
54-
* Tablet
55-
* Web
56-
* HandsetPortrait
57-
* TabletPortrait
58-
* WebPortrait
59-
* HandsetLandscape
60-
* TabletLandscape
61-
* WebLandscape
57+
You can use these predefined breakpoints with `BreakpointObserver`.
6258

59+
```ts
60+
breakpointObserver.observe([
61+
Breakpoints.HandsetLandscape,
62+
Breakpoints.HandsetPortrait
63+
]).subscribe(result => {
64+
if (result.matches) {
65+
this.activateHandsetLayout();
66+
}
67+
});
68+
```
6369

6470
### MediaMatcher
65-
`MediaMatcher` is a lower-level utility that wraps the native `matchMedia`. This service normalizes
66-
browser differences and serves as a convenient API that can be replaced with a fake in unit tests.
71+
`MediaMatcher` is a low-level utility that wraps the native `matchMedia`. This service
72+
normalizes browser differences and serves as a convenient API that can be replaced with a fake in
73+
unit tests.
6774
The `matchMedia` method can be used to get a native
6875
[`MediaQueryList`](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList).
6976

0 commit comments

Comments
 (0)