You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
⚠️ **Caution** — `Provider` instantiates a `window.ResizeObserver` by default. [`window.ResizeObserver` currently has weak browser support](https://caniuse.com/#feat=mdn-api_resizeobserver_resizeobserver). You may pass a `ResizeObserver` constructor to `Provider` to use instead of `window.ResizeObserver`. I recommend [ponyfilling](https://ponyfill.com) using [`@juggle/resize-observer`](https://github.com/juggle/resize-observer). You can also [monkey patch](https://en.wikipedia.org/wiki/Monkey_patch)`window.ResizeObserver` and use `Provider` without the `ponyfill` prop.
36
+
</details>
33
37
34
38
## Usage
35
39
@@ -50,7 +54,7 @@ const App = () => (
50
54
51
55
You can observe size changes of an element's `box` by rendering it through `<Observe>`'s `render` prop. Your render function receives a `observedElementProps` argument that you spread onto the DOM element you wish to observe. It also receives `widthMatch` and `heightMatch` arguments which match the values you assigned via `<Observe>`'s `breakpoints` prop.
52
56
53
-
⚠️ **Important** — There is an important distinction between the `box` you're observing and `box`es triggering breakpoints. See [Observing boxes vs. Matching boxes](boxes.md) for more information.
57
+
⚠️ **Important** — There is an important distinction between the `box` you observe and the `box` you consume for triggering breakpoints. See [Observing vs. Consuming Boxes](boxes.md) for more information.
54
58
55
59
## Reference guide
56
60
@@ -104,6 +108,43 @@ You can observe size changes of an element's `box` by rendering it through `<Obs
Depending on your implementation of `ResizeObserver`, the [internal `ResizeObserverEntry`](#useresizeobserverentry) can contain size information about multiple "boxes" of the observed element.
115
+
116
+
This library supports observing the following `box` options (but your browser may not!):
If `box` is left `undefined` or set to any value other than those listed above, `<Observe>` will default to using information from `ResizeObserverEntry.contentRect`.
123
+
124
+
⚠️ **Important** — There is an important distinction between the `box` you observe and the `box` you consume for triggering breakpoints. See [Observing vs. Consuming Boxes](boxes.md) for more information.
Using the `...` spread operator, you apply this object to the DOM element you want to observe.
140
+
*`widthMatch` — <small><code>any</code></small>
141
+
If you passed an object with a `widths` property to the `breakpoints` prop, this argument contains the currently matching width breakpoint value.
142
+
*`heightMatch` — <small><code>any</code></small>
143
+
If you passed an object with a `heights` property to the `breakpoints` prop, this argument contains the currently matching height breakpoint value.
144
+
145
+
Your function should at least return some JSX with `{...observedElementProps}` applied to a DOM element.
146
+
</details>
147
+
107
148
## Usage
108
149
109
150
```javascript
@@ -161,12 +202,19 @@ The hook takes an `options` object as its first argument, which must include a `
161
202
162
203
Optionally, you can include a `box` property, which — depending on your implementation of `ResizeObserver` — can target different observable "boxes" of an element. By default, the legacy `contentRect` property will be used by `useBreakpoints()`.
163
204
164
-
The hook takes a optional `ResizeObserverEntry` as its second argument. **If you pass one, `useBreakpoints()` will not fetch it from the [context](#context), so use caution!**
205
+
The hook takes an optional `ResizeObserverEntry` as its second argument. **If you pass one, `useBreakpoints()` will not fetch it from the [context](#context), so use caution!**
165
206
166
207
## Reference guide
167
208
168
209
```javascript
169
-
const [widthValue, heightValue] =useBreakpoints({
210
+
/* returns an array of matched breakpoint values */
211
+
const [
212
+
/* first element is the matched value from `widths` */
213
+
widthValue,
214
+
215
+
/* second element is the matched value from `heights` */
216
+
heightValue
217
+
] =useBreakpoints({
170
218
/* (optional) target a box size of the observed element to match widths and heights on */
Depending on your implementation of `ResizeObserver`, the [internal `ResizeObserverEntry`](#useResizeObserverEntry) can contain size information about multiple "boxes" of the observed element.
249
+
Depending on your implementation of `ResizeObserver`, the [internal `ResizeObserverEntry`](#useresizeobserverentry) can contain size information about multiple "boxes" of the observed element.
203
250
204
251
This library supports the following `box` options (but your browser may not!):
205
252
@@ -209,11 +256,11 @@ This library supports the following `box` options (but your browser may not!):
209
256
210
257
If `box` is left `undefined` or set to any value other than those listed above, `useBreakpoints()` will default to using information from `ResizeObserverEntry.contentRect`.
211
258
212
-
⚠️ **Important** — There is an important distinction between the `box` you're observing and `box`es triggering breakpoints. See [Observing boxes vs. Matching boxes](boxes.md) for more information.
259
+
⚠️ **Important** — There is an important distinction between the `box` you observe and the `box` you consume for triggering breakpoints. See [Observing vs. Consuming Boxes](boxes.md) for more information.
`widths` must be an object with numbers as its keys. The numbers represent the minimum width the `box` must have for that key's value to be returned. The value of the highest matching width will be returned.
`heights` must be an object with numbers as its keys. The numbers represent the minimum height the `box` must have for that key's value to be returned. The value of the highest matching height will be returned.
275
322
@@ -286,15 +333,22 @@ heights: {
286
333
287
334
⚠️ **Caution**: If you do not provide `0` as a key for `heights`, you risk receiving `undefined` as a return value. This is intended behaviour, but makes it difficult to distinguish between receiving `undefined` because of a [Server-Side Rendering](server-side-rendering.md) scenario, or because the observed height is less than the next matching height.
288
335
289
-
Values can be of _any_ type, you are not restricted to return `string` values. See example in [`widths`](#widths) section above.
290
-
291
-
### `fragment`
336
+
Values can be of _any_ type, you are not restricted to return `string` values. See example in `widths` section above.
The box sizes are exposed as sequences in order to support elements that have multiple fragments, which occur in multi-column scenarios. You can specify which fragment's size information to use for matching `widths` and `heights` by setting this prop. Defaults to the first fragment.
296
343
297
-
See [W3C Editor's Draft](https://drafts.csswg.org/resize-observer-1/#resize-observer-entry-interface) for more information about fragments.
344
+
See the [W3C Editor's Draft](https://drafts.csswg.org/resize-observer-1/#resize-observer-entry-interface) for more information about fragments.
Allows you to force `useBreakpoints()` to use the `ResizeObserverEntry` you pass here in its calculations rather than retrieving the entry that's on the closest [`<Context>`](#context).
⚠️ **Advanced usage** — This hook is used internally in [`<Observe>`](#observe) to:
364
418
* start and stop observing an element by passing a `ref` to a DOM element;
365
-
* bind a standardised callback to all observations, and set the `ObservedEntry` on a [`<Context>`](#context).
419
+
* bind a standardised callback to all observations, and set the `observedEntry` on a [`<Context>`](#context).
366
420
367
421
This hook takes an optional `options` object argument, which currently only supports a `box` option.
368
422
369
-
### `box`
370
-
371
-
> `String` <sup>optional</sup>
372
-
373
-
Depending on your implementation of `ResizeObserver`, you may observe one of multiple "boxes" of an element to trigger an update of `observedEntry`. By default this option is not set, and the size information of the observed element comes from the legacy `contentRect` property.
374
-
375
-
This library supports the following `box` options (but your browser may not!):
⚠️ **Important** — There is an important distinction between the `box` you're observing and `box`es triggering breakpoints. See [Observing boxes vs. Matching boxes](boxes.md) for more information.
Depending on your implementation of `ResizeObserver`, you may observe one of multiple "boxes" of an element to trigger an update of `observedEntry`. By default this option is not set, and the size information of the observed element comes from the legacy `contentRect` property.
445
+
446
+
This library supports the following `box` options (but your browser may not!):
⚠️ **Important** — There is an important distinction between the `box` you observe and the `box` you consume for triggering breakpoints. See [Observing vs. Consuming Boxes](boxes.md) for more information.
⚠️ **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](#box).
560
+
⚠️ **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.
Copy file name to clipboardExpand all lines: docs/boxes.md
+9-6Lines changed: 9 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,14 @@
1
-
# Observing boxes vs. Matching boxes
1
+
# Observing vs. Consuming boxes
2
2
3
-
There is an important distinction between the `box` you're observing and `box`es triggering breakpoints.
3
+
There is an important distinction between the `box` you observe and the `box` you consume for triggering breakpoints.
4
4
5
5
> You can observe a box on an element, and then respond to changes in **another** box of that element.
6
6
7
-
There might be cases where observing the same box you're matching breakpoints against is not desirable. **This package supports observing and matching on different boxes.**
7
+
There might be cases where observing the same box you're matching breakpoints against is not desirable. **This package supports observing and consuming different boxes on the same element.**
8
+
9
+
<details>
10
+
<summary><big>What's happening under the hood?</big></summary>
8
11
9
-
## What's happening under the hood?
10
12
11
13
Consider this example code and chain of events:
12
14
@@ -53,6 +55,7 @@ const ChildComponent = () => {
53
55
1. Because `border-box` is not observed, `<Observe>`'s context does not get updated, and therefore `<ChildComponent>` does not update.
54
56
1. Finally, after a while longer, the element's `device-pixel-content-box` size changes.
55
57
1. Even though `<ChildComponent>` uses this box's size, `<Observe>` is not observing changes on this box, and does not update its context to inform `<ChildComponent>`.
58
+
</details>
56
59
57
60
# ⚠️ Important
58
61
@@ -62,7 +65,7 @@ Consider the [CSS box model](https://en.wikipedia.org/wiki/CSS_box_model#/media/
62
65
63
66
64
67
65
-
When padding or border increase in thickness, the content's size will remain unaffected. If you are observing changes in `content-box`'s size, those padding and border changes will not trigger any updates.
68
+
When padding or border increase in thickness, the content's size will remain unaffected. If you are observing changes in `content-box`'s size, those padding and border changes **will not trigger any updates**.
66
69
67
70
Similarly, let's say you have the following element:
68
71
@@ -72,4 +75,4 @@ Similarly, let's say you have the following element:
72
75
</div>
73
76
```
74
77
75
-
Then you change that element's `padding` to `0`. If you are observing changes in this element's `border-box` size, this padding change will not trigger any updates because the `border-box` did not change size.
78
+
Then you change that element's `padding` to `0`. If you are observing changes in this element's `border-box` size, this padding change **will not trigger any updates** because the `border-box` did not change size.
0 commit comments