Skip to content

Commit ea2510a

Browse files
mdingenamdingena
committed
Update documentation
1 parent d44bd8e commit ea2510a

3 files changed

Lines changed: 63 additions & 78 deletions

File tree

‎README.md‎

Lines changed: 21 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@
55
<h1 align="center">React Breakpoints</h1>
66

77
<p align="center">
8-
<img alt="dependent repositories" src="https://img.shields.io/librariesio/dependent-repos/npm/@envato/react-breakpoints?label=Used%20by&style=for-the-badge" />
98
<img alt="npm version" src="https://img.shields.io/npm/v/@envato/react-breakpoints?style=for-the-badge" />
109
<img alt="react version" src="https://img.shields.io/npm/dependency-version/@envato/react-breakpoints/dev/react?style=for-the-badge">
1110
<img alt="license" src="https://img.shields.io/npm/l/@envato/react-breakpoints?style=for-the-badge" />
@@ -21,13 +20,12 @@
2120
2221
This package provides you with:
2322

24-
* a [`<Provider>`](/docs/api.md#provider) to instantiate the ResizeObserver;
25-
* an [`<Observe>`](/docs/api.md#observe) component to observe changes in a DOM element;
26-
* a [`useBreakpoints()`](/docs/api.md#usebreakpoints) hook to change a component's behaviour based on the observed size information in the nearest parent `<Observe>`.
23+
* a [`<Provider>`](/docs/api.md#provider) to instantiate the `ResizeObserver`;
24+
* an [`<Observe>`](/docs/api.md#observe) component to observe changes in a DOM element and respond to them.
2725

2826
For power users this package also provides:
2927

30-
* a [`<Context>`](/docs/api.md#context) on which you can assign a `ResizeObserverEntry` value to update any nested components that are using `useBreakpoints()`;
28+
* a [`useBreakpoints()`](/docs/api.md#usebreakpoints) hook to change a component's behaviour based on the observed size information in the nearest parent `<Observe>`;
3129
* a [`useResizeObserver()`](/docs/api.md#useresizeobserver) hook to connect a DOM element in your component to the instantiated `ResizeObserver` on `<Provider>`;
3230
* a [`useResizeObserverEntry()`](/docs/api.md#useresizeobserverentry) hook to retrieve the `ResizeObserverEntry` put on the nearest `<Context>`. This is what `useBreakpoints()` uses under the hood.
3331

@@ -59,56 +57,41 @@ const App = () => (
5957

6058
## Observe an element
6159

62-
Everything you render through `<Observe>` becomes aware of the size of the element that is given `{...observedElementProps}`. This is called an "Observe Scope".
60+
Everything you render through `<Observe>` has access to the size of the element that is given `{...observedElementProps}`. This is called the "Observe Scope".
6361

6462
```javascript
6563
import { Observe } from '@envato/react-breakpoints';
6664

6765
const MyObservingComponent = () => (
6866
<Observe
69-
render={({ observedElementProps }) => (
70-
<aside {...observedElementProps}>
71-
<MyResponsiveComponent />
72-
</aside>
67+
breakpoints={{
68+
widths: {
69+
0: 'mobile',
70+
769: 'tablet',
71+
1025: 'desktop'
72+
}
73+
}}
74+
render={({ observedElementProps, widthMatch = 'ssr' }) => (
75+
<div {...observedElementProps}>
76+
<div className={widthMatch}>
77+
</div>
7378
)}
7479
/>
7580
);
7681
```
7782

78-
## Consume the observation
79-
80-
Components that are rendered within the "Observe Scope" can consume observation results via `useBreakpoints()`:
81-
82-
```javascript
83-
import { useBreakpoints } from '@envato/react-breakpoints';
84-
85-
const MyResponsiveComponent = () => {
86-
const options = {
87-
widths: {
88-
0: 'mobile',
89-
769: 'tablet',
90-
1025: 'desktop'
91-
}
92-
};
93-
94-
const [label] = useBreakpoints(options);
95-
96-
return (
97-
<div className={label}>
98-
This element is currently within the {label} range.
99-
</div>
100-
);
101-
};
102-
```
103-
104-
However, `<Observe>` supports additional props allowing you to observe **and** consume observations — no `useBreakpoints()` required!
105-
10683
See the [API Docs](/docs/api.md) for reference guides and usage examples.
10784

10885
# Observing vs. Consuming boxes
10986

11087
There is an important distinction between the `box` you observe and the `box` you consume for triggering breakpoints. See [Observing vs. Consuming Boxes](/docs/boxes.md) for more information.
11188

89+
# Re-rendering
90+
91+
Using [`useResizeObserver()`](/docs/api.md#useresizeobserver), [`useResizeObserverEntry()`](/docs/api.md#useresizeobserverentry) or [`useBreakpoints()`](/docs/api.md#usebreakpoints) in your components causes them to re-render **every time a resize is observed**.
92+
93+
In some cases, you may want to optimise this. If you only want to re-render your components when breakpoint values actually change, use `React.useMemo` or `React.memo`.
94+
11295
# Server-Side Rendering
11396

11497
See [Server-Side Rendering](/docs/server-side-rendering.md) for more information.

‎docs/api.md‎

Lines changed: 40 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,13 @@ Common usage:
44

55
* [`<Provider>`](#provider)
66
* [`<Observe>`](#observe)
7-
* [`useBreakpoints()`](#usebreakpoints)
87

98
Advanced usage:
109

11-
* [`<Context>`](#context)
10+
* [`useBreakpoints()`](#usebreakpoints)
1211
* [`useResizeObserver()`](#useresizeobserver)
1312
* [`useResizeObserverEntry()`](#useresizeobserverentry)
13+
* [`<Context>`](#context)
1414

1515
---
1616

@@ -196,6 +196,8 @@ const MyObservingComponent = () => (
196196

197197
# `useBreakpoints()`
198198

199+
⚠️ **Advanced usage** — This hook is used internally in [`<Observe>`](#observe) to enable the use of the optional `breakpoints` prop.
200+
199201
Components inside an "[`<Observe>`](#observe) scope" have access to its observations. The observed element's sizes are available on a [context](#context) via the `useBreakpoints()` hook.
200202

201203
The hook takes an `options` object as its first argument, which must include a `widths` or `heights` key (or both) with an object as its value. That object must have a shape of numbers as keys, and a value of any type. The value you set here is what will eventually be returned by `useBreakpoints()`.
@@ -376,42 +378,6 @@ const MyResponsiveComponent = () => {
376378

377379
---
378380

379-
# `<Context>`
380-
381-
⚠️ **Advanced usage** — This React context is used internally by [`useBreakpoints()`](#usebreakpoints). You may use this context with `React.useContext()` to access the information stored in the context provider, which is typically a `ResizeObserverEntry` set internally by [`<Observe>`](#observe).
382-
383-
## Reference guide
384-
385-
```javascript
386-
<Context.Provider value={ResizeObserverEntry}>
387-
```
388-
389-
## Usage
390-
391-
`parent.js`
392-
```javascript
393-
import { Context } from '@envato/react-breakpoints';
394-
395-
<Context.Provider value={myResizeObserverEntry}>
396-
/* children with access to `myResizeObserverEntry` */
397-
</Context.Provider>
398-
```
399-
400-
`child.js`
401-
```javascript
402-
import { useContext } from 'react';
403-
import { Context } from '@envato/react-breakpoints';
404-
405-
const MyChildComponent = () => {
406-
const myResizeObserverEntry = useContext(Context);
407-
/* ... */
408-
};
409-
```
410-
411-
⚠️ **Hint** — Instead of manually implementing the `child.js` portion as above, you may want to use [`useResizeObserverEntry()`](#useresizeobserverentry) instead.
412-
413-
---
414-
415381
# `useResizeObserver()`
416382

417383
⚠️ **Advanced usage** — This hook is used internally in [`<Observe>`](#observe) to:
@@ -563,3 +529,39 @@ const MyResponsiveComponent = () => {
563529
```
564530

565531
⚠️ **Hint** — You probably don't need this hook, because [`useBreakpoints()`](#usebreakpoints) abstracts the above implementation away for your convenience. You'll likely only need this hook if you need a property from `ResizeObserverEntry` which is not `contentRect` or one of `box`'s options.
532+
533+
---
534+
535+
# `<Context>`
536+
537+
⚠️ **Internal usage, you probably don't need this!** — This React context is used internally by [`useBreakpoints()`](#usebreakpoints). You may use this context with `React.useContext()` to access the information stored in the context provider, which is typically a `ResizeObserverEntry` set internally by [`<Observe>`](#observe).
538+
539+
## Reference guide
540+
541+
```javascript
542+
<Context.Provider value={ResizeObserverEntry}>
543+
```
544+
545+
## Usage
546+
547+
`parent.js`
548+
```javascript
549+
import { Context } from '@envato/react-breakpoints';
550+
551+
<Context.Provider value={myResizeObserverEntry}>
552+
/* children with access to `myResizeObserverEntry` */
553+
</Context.Provider>
554+
```
555+
556+
`child.js`
557+
```javascript
558+
import { useContext } from 'react';
559+
import { Context } from '@envato/react-breakpoints';
560+
561+
const MyChildComponent = () => {
562+
const myResizeObserverEntry = useContext(Context);
563+
/* ... */
564+
};
565+
```
566+
567+
⚠️ **Hint** — Instead of manually implementing the `child.js` portion as above, you may want to use [`useResizeObserverEntry()`](#useresizeobserverentry) instead.

‎docs/server-side-rendering.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Server-Side Rendering
22

3-
The values returned from [`useBreakpoints()`](api.md#usebreakpoints) default to `undefined`, which is the case when:
3+
The `widthMatch` and `heightMatch` values returned from [`<Observe>`](api.md#observe) and [`useBreakpoints()`](api.md#usebreakpoints) default to `undefined`. This is the case when:
44

5-
* the observed min-size isn't specified in your [`options`](api.md#widths);
5+
* the observed min-size isn't specified in your [`options`](api.md#usebreakpoints);
66
* rendering a component server-side.
77

88
You can use this `undefined` value to display your component differently for SSR purposes. How you do it is up to you (loading component, default CSS styles, placeholder content, `null`, etc).

0 commit comments

Comments
 (0)