Skip to content

Commit 376b3f4

Browse files
garthenwebgarthenweb
committed
docs(hooks): document new apis
1 parent 7d749e8 commit 376b3f4

File tree

4 files changed

+144
-12
lines changed

4 files changed

+144
-12
lines changed

‎README.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -56,11 +56,16 @@ The project aims to support recent releases of v8 and v10 and higher of NodeJS.
5656
* [`ViewportProvider`](docs/api/ViewportProvider.md)
5757
* [`ObserveViewport`](docs/api/ObserveViewport_connectViewport_useViewport.md#render-props-event-handler-observeviewport)
5858
* [`connectViewport`](docs/api/ObserveViewport_connectViewport_useViewport.md#hoc-connectviewport)
59-
* [`NEW useViewport`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
60-
* [`NEW useScroll`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
61-
* [`NEW useDimensions`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
62-
* [`NEW useLayoutSnapshot`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
63-
* [`ObserveBoundingClientRect (deprecated)`](docs/api/ObserveBoundingClientRect.md)
59+
* [`useViewport`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
60+
* [`useScroll`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
61+
* [`useDimensions`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
62+
* [`useLayoutSnapshot`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
63+
* [`NEW useViewportEffect`](docs/api/ObserveViewport_connectViewport_useViewport.md#hook-effects-useViewportEffect-useScrollEffect-useDimensionsEffect)
64+
* [`NEW useScrollEffect`](docs/api/ObserveViewport_connectViewport_useViewport.md#hook-effects-useViewportEffect-useScrollEffect-useDimensionsEffect)
65+
* [`NEW useDimensionsEffect`](docs/api/ObserveViewport_connectViewport_useViewport.md#hook-effects-useViewportEffect-useScrollEffect-useDimensionsEffect)
66+
* [`NEW useRect`](docs/api/useRect.md#useRect)
67+
* [`NEW useRectEffect`](docs/api/useRect.md#useRectEffect)
68+
* [`DEPRECATED ObserveBoundingClientRect`](docs/api/ObserveBoundingClientRect.md)
6469
* [Types](docs/api/types.md)
6570

6671
### Concepts

‎docs/api/ObserveViewport_connectViewport_useViewport.md

Lines changed: 43 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -86,18 +86,16 @@ render(
8686

8787
## Hooks: `useViewport`, `useScroll`, `useDimensions`, `useLayoutSnapshot`
8888

89-
[Hooks](https://reactjs.org/docs/hooks-intro.html) are probably the easiest way to update your components but as of now needs to be consumed with care because this API and hooks in general are in early stage and thus are may contain bugs or will undergo breaking changes. As always, please report bugs if you find some.
90-
9189
**!!! Hooks require a `ViewportProvider` as a parent and only work with react v16.7.0 !!!**
9290

9391
### API
9492

95-
| Property | Type | Required? | Description |
93+
| Argument | Type | Required? | Description |
9694
|:---|:---|:---:|:---|
97-
| disableScrollUpdates | boolean | | Disables updates to scroll events (only for `useViewport` and `useLayoutSnapshot`) |
98-
| disableDimensionsUpdates | boolean | | Disables updates to dimensions events (only for `useViewport` and `useLayoutSnapshot`) |
99-
| deferUpdateUntilIdle | boolean | | Defers to trigger updates until the collector is idle. See [Defer Events](../concepts/defer_events.md) |
100-
| priority | `'low'`, `'normal'`, `'high'`, `'highest'` | | Allows to set a priority of the update. See [Defer Events](../concepts/scheduler.md) |
95+
| options.disableScrollUpdates | boolean | | Disables updates to scroll events (only for `useViewport` and `useLayoutSnapshot`) |
96+
| options.disableDimensionsUpdates | boolean | | Disables updates to dimensions events (only for `useViewport` and `useLayoutSnapshot`) |
97+
| options.deferUpdateUntilIdle | boolean | | Defers to trigger updates until the collector is idle. See [Defer Events](../concepts/defer_events.md) |
98+
| options.priority | `'low'`, `'normal'`, `'high'`, `'highest'` | | Allows to set a priority of the update. See [Defer Events](../concepts/scheduler.md) |
10199

102100
### Example
103101

@@ -120,6 +118,44 @@ function Component() {
120118
}
121119
```
122120

121+
## Hook Effects: `useViewportEffect`, `useScrollEffect`, `useDimensionsEffect`
122+
123+
Hook effects allow to trigger side effects on change without updating the component.
124+
125+
**!!! Hooks require a `ViewportProvider` as a parent and only work with react v16.7.0 !!!**
126+
127+
### API
128+
129+
| Argument | Type | Required? | Description |
130+
|:---|:---|:---:|:---|
131+
| effect | (IViewport \| IScroll \| IDimensions) => void | x | Disables updates to scroll events (only for `useViewport`) |
132+
| options.disableScrollUpdates | boolean | | Disables updates to scroll events (only for `useViewport`) |
133+
| options.disableDimensionsUpdates | boolean | | Disables updates to dimensions events (only for `useViewport`) |
134+
| options.deferUpdateUntilIdle | boolean | | Defers to trigger updates until the collector is idle. See [Defer Events](../concepts/defer_events.md) |
135+
| options.priority | `'low'`, `'normal'`, `'high'`, `'highest'` | | Allows to set a priority of the update. See [Defer Events](../concepts/scheduler.md) |
136+
| options.recalculateLayoutBeforeUpdate | function | | Enables a way to calculate layout information for all components as a badge before the effect call. Contains `IViewport`, `IScroll` or `IDimensions` as the first argument, dependent of the used hook. See [recalculateLayoutBeforeUpdate](../concepts/recalculateLayoutBeforeUpdate.md) |
137+
138+
### Example
139+
140+
``` javascript
141+
import * as React from 'react';
142+
import { useScrollEffect, useViewportEffect } from 'react-viewport-utils';
143+
144+
function Component() {
145+
const ref = React.useRef()
146+
useScrollEffect((scroll) => {
147+
console.log(scroll);
148+
});
149+
useViewportEffect((viewport, elementWidth) => {
150+
console.log(viewport, top);
151+
}, {
152+
recalculateLayoutBeforeUpdate: () => ref.current ? ref.current.getBoundingClientRect().width : null
153+
});
154+
155+
return <div ref={ref} />;
156+
}
157+
```
158+
123159
## Related docs
124160

125161
* [ViewportProvider](./ViewportProvider.md)

‎docs/api/types.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,3 +36,15 @@ For scroll events the `scroll` object is exposed which contains the following pr
3636
|:---|:---|:---|
3737
| scroll | IScroll | See IScroll type above |
3838
| dimensions | IDimensions | See IDimensions type above |
39+
40+
41+
## IRect
42+
43+
| Property | Type | Description |
44+
|:---|:---|:---|
45+
| top | number | Top position of the element, relative to the viewport |
46+
| right | number | Right position of the element, relative to the viewport |
47+
| bottom | number | Bottom position of the element, relative to the viewport |
48+
| left | number | Left position of the element, relative to the viewport |
49+
| width | number | Width of the element |
50+
| height | number | Height of the element |

‎docs/api/useRect.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Observe an element
2+
3+
## `useRect`
4+
5+
Returns the rect of the elements, including it's position within the viewport as well as it's size.
6+
7+
Please note that at the moment the rect will only update after global scroll or resize events. Changes to the element without those interactions will not be observed (e.g. if an animation is performed).
8+
In case you need full control over the element, I recommend using the [ResizeObserver DOM API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
9+
10+
**!!! Hooks require a `ViewportProvider` as a parent and only work with react v16.7.0 !!!**
11+
12+
### API
13+
14+
| Argument | Type | Required? | Description |
15+
|:---|:---|:---:|:---|
16+
| ref | React.RefObject\<HTMLElement> | x | The reference to an element that should be observed |
17+
| options.disableScrollUpdates | boolean | | Disables updates to scroll events (only for `useViewport`) |
18+
| options.disableDimensionsUpdates | boolean | | Disables updates to dimensions events (only for `useViewport`) |
19+
| options.deferUpdateUntilIdle | boolean | | Defers to trigger updates until the collector is idle. See [Defer Events](../concepts/defer_events.md) |
20+
| options.priority | `'low'`, `'normal'`, `'high'`, `'highest'` | | Allows to set a priority of the update. See [Defer Events](../concepts/scheduler.md) |
21+
22+
### Example
23+
24+
``` javascript
25+
import * as React from 'react';
26+
import { useRect } from 'react-viewport-utils';
27+
28+
function Component() {
29+
const ref = React.useRef()
30+
const rect = useRect(ref) || {
31+
width: NaN,
32+
height: NaN,
33+
};
34+
35+
return (
36+
<div ref={ref}>
37+
Current Size is {rect.width}x{rect.width}
38+
</div>
39+
);
40+
}
41+
```
42+
43+
## `useRectEffect`
44+
45+
Same as the `useRect` hook but as an effect, therefore it does not return anything and will not re-render the component. This should be used if a side effect should be performed.
46+
47+
**!!! Hooks require a `ViewportProvider` as a parent and only work with react v16.7.0 !!!**
48+
49+
### API
50+
51+
| Argument | Type | Required? | Description |
52+
|:---|:---|:---:|:---|
53+
| effect | (rect: IRect \| null) => void | x | The side effect that should be performed |
54+
| ref | React.RefObject\<HTMLElement> | x | The reference to an element that should be observed |
55+
| options.disableScrollUpdates | boolean | | Disables updates to scroll events (only for `useViewport`) |
56+
| options.disableDimensionsUpdates | boolean | | Disables updates to dimensions events (only for `useViewport`) |
57+
| options.deferUpdateUntilIdle | boolean | | Defers to trigger updates until the collector is idle. See [Defer Events](../concepts/defer_events.md) |
58+
| options.priority | `'low'`, `'normal'`, `'high'`, `'highest'` | | Allows to set a priority of the update. See [Defer Events](../concepts/scheduler.md) |
59+
60+
### Example
61+
62+
``` javascript
63+
import * as React from 'react';
64+
import { useRectEffect } from 'react-viewport-utils';
65+
66+
function Component() {
67+
const ref = React.useRef()
68+
useRectEffect((rect) => console.log(rect), ref)
69+
70+
return (
71+
<div ref={ref} />
72+
);
73+
}
74+
```
75+
76+
## Related docs
77+
78+
* [ViewportProvider](./ViewportProvider.md)
79+
* [Types](./types.md)

0 commit comments

Comments
 (0)