Skip to content

docs(cdk/layout): better explain how layout breakpoints work #22821

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 27, 2021
Merged

docs(cdk/layout): better explain how layout breakpoints work #22821

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 46 additions & 39 deletions src/cdk/layout/layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,24 @@ The `layout` package provides utilities to build responsive UIs that react to sc

### BreakpointObserver

`BreakpointObserver` is a utility for evaluating media queries and reacting to changes in the results of those queries.
A layout **breakpoint** is viewport size threshold at which a layout shift can occur. The viewport
size ranges between breakpoints correspond to different standard screen sizes.

`BreakpointObserver` lets you evaluate media queries to determine the current screen size and
react to changes when the viewport size crosses a breakpoint.

#### Check the current viewport size
You can use the `isMatched` method to evaluate one or more media queries against the current
viewport size.

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

#### React to changes to the viewport
The `observe` method is used to get an observable stream that will emit whenever one of the given
media queries would have a different result.
You can use the `observe` method to get an observable stream that emits whenever the viewport size
crosses a breakpoint.

```ts
const layoutChanges = breakpointObserver.observe([
'(orientation: portrait)',
Expand All @@ -25,45 +31,46 @@ layoutChanges.subscribe(result => {
});
```

#### Default breakpoints
A set of default media queries are available corresponding to breakpoints for different device
types.
#### Predefined breakpoints

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

@Component({...})
class MyComponent {
constructor(breakpointObserver: BreakpointObserver) {
breakpointObserver.observe([
Breakpoints.HandsetLandscape,
Breakpoints.HandsetPortrait
]).subscribe(result => {
if (result.matches) {
this.activateHandsetLayout();
}
});
}
}
```
| Breakpoint name | Media query |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| `XSmall` | `(max-width: 599.98px)` |
| `Small` | `(min-width: 600px) and (max-width: 959.98px)` |
| `Medium` | `(min-width: 960px) and (max-width: 1279.98px)` |
| `Large` | `(min-width: 1280px) and (max-width: 1919.98px)` |
| `XLarge` | `(min-width: 1920px)` |
| `Handset` | `(max-width: 599.98px) and (orientation: portrait), (max-width: 959.98px) and (orientation: landscape)` |
| `Tablet` | `(min-width: 600px) and (max-width: 839.98px) and (orientation: portrait), (min-width: 960px) and (max-width: 1279.98px) and (orientation: landscape)` |
| `Web` | `(min-width: 840px) and (orientation: portrait), (min-width: 1280px) and (orientation: landscape)` |
| `HandsetPortrait` | `(max-width: 599.98px) and (orientation: portrait)` |
| `TabletPortrait` | `(min-width: 600px) and (max-width: 839.98px) and (orientation: portrait)` |
| `WebPortrait` | `(min-width: 840px) and (orientation: portrait)` |
| `HandsetLandscape` | `(max-width: 959.98px) and (orientation: landscape)` |
| `TabletLandscape` | `(min-width: 960px) and (max-width: 1279.98px) and (orientation: landscape)` |
| `WebLandscape` | `(min-width: 1280px) and (orientation: landscape)` |

The built-in breakpoints based on [Google's Material Design
specification](https://material.io/design/layout/responsive-layout-grid.html#breakpoints).
The available values are:
* Handset
* Tablet
* Web
* HandsetPortrait
* TabletPortrait
* WebPortrait
* HandsetLandscape
* TabletLandscape
* WebLandscape
You can use these predefined breakpoints with `BreakpointObserver`.

```ts
breakpointObserver.observe([
Breakpoints.HandsetLandscape,
Breakpoints.HandsetPortrait
]).subscribe(result => {
if (result.matches) {
this.activateHandsetLayout();
}
});
```

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

Expand Down