Skip to content

Commit f68a1dc

Browse files
jelbournjelbourn
authored
docs(cdk/layout): better explain how layout breakpoints work (#22821)
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 d198cb5 commit f68a1dc

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)