Skip to content

Commit 652d3ea

Browse files
committed
update README.md with new interface & package.json as well as lockfile
1 parent c42ae30 commit 652d3ea

File tree

3 files changed

+47
-38
lines changed

3 files changed

+47
-38
lines changed

README.md

Lines changed: 36 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -27,13 +27,11 @@ npm install -D use-viewport-sizes
2727
<center>
2828
<img src="./doc/use-viewport-sizes.gif" />
2929

30-
[CodeSandbox IDE](https://codesandbox.io/s/react-hooks-viewport-sizes-demo-forked-i8urr) |
31-
[CodeSandbox DEMO](https://codesandbox.io/s/react-hooks-viewport-sizes-demo-forked-i8urr)
32-
30+
[CodeSandbox IDE](https://codesandbox.io/s/react-hooks-viewport-sizes-demo-forked-i8urr)
3331

3432
</center>
3533

36-
### **Without Debouncing**
34+
### **Basic Use-case**
3735
*registers dimension changes on every resize event immediately*
3836

3937
```js
@@ -47,29 +45,49 @@ function MyComponent(props) {
4745
}
4846
```
4947

48+
### **Measure/Update only on one dimension**
49+
50+
If passed `options.dimension` as `w` or `h`, only the viewport width or height will be
51+
measured and observed for updates.
52+
The only dimension returned in the return array value will be the width or height, according
53+
to what was passed.
54+
55+
```js
56+
import React from 'react';
57+
import useViewportSizes from 'use-viewport-sizes';
58+
59+
function MyComponent(props) {
60+
const [vpHeight] = useViewportSizes({ dimension: 'h' });
61+
62+
...renderLogic
63+
}
64+
```
65+
5066

5167
### **With Debouncing**
5268

53-
If passed a number as the first argument, it registers dimension changes only when a user stops dragging/resizing the window for a specified number of miliseconds. This is useful for listening to expensive components such as data grids which may be too
69+
If passed `options.debounceTimeout`, or options are entered as a `Number`, it registers dimension changes only when a user stops dragging/resizing the window for a specified number of miliseconds. This is useful for listening to expensive components such as data grids which may be too
5470
expensive to re-render during window resize dragging.
71+
5572
```js
56-
import React from 'react'
57-
import useViewportSizes from 'use-viewport-sizes'
73+
import React from 'react';
74+
import useViewportSizes from 'use-viewport-sizes';
5875

59-
function MyExpensivelyRenderedComponent (props) {
60-
const [vpWidth, vpHeight] = useViewportSizes(1000); // 1s debounce
76+
function MyExpensivelyRenderedComponent(props) {
77+
const [vpWidth, vpHeight] = useViewportSizes({ debounceTimeout: 1000 }); // 1s debounce
6178

62-
...renderLogic
79+
// ...renderLogic
6380
}
6481
```
6582

6683
### **Only update vpW/vpH passed on specific conditions**
67-
If passed a function as the first argument, it will use this to calculate a hash that only updates the viewport when the calculation changes. In the example here, we are using it to detect when we have a breakpoint change which may change how a component is rendered if this is not fully possible or inconvenient via CSS `@media` queries. The hash will also be available as the 3rd value returned from the hook for convenience.
84+
If passed an `options.hasher` function, this will be used to calculate a hash that only updates the viewport when the calculation changes. In the example here, we are using it to detect when we have a breakpoint change which may change how a component is rendered if this is not fully possible or inconvenient via CSS `@media` queries. The hash will also be available as the 3rd value returned from the hook for convenience.
85+
6886
```js
6987
import React from 'react';
7088
import useViewportSizes from 'use-viewport-sizes';
7189

72-
function getBreakpoint({ vpW, vpH }) {
90+
function getBreakpointHash({ vpW, vpH }) {
7391
if(vpW < 640) {
7492
return 'md';
7593
}
@@ -85,7 +103,7 @@ function getBreakpoint({ vpW, vpH }) {
85103
}
86104

87105
function MyBreakpointBehaviorComponent() {
88-
const [vpW, vpH, bp] = useViewportSizes(getBreakpoint);
106+
const [vpW, vpH, bp] = useViewportSizes({ hasher: getBreakpointHash });
89107

90108
// do-something-with-breakpoints in render
91109
// and add new update for vpW, vpH in this component's
@@ -96,24 +114,24 @@ function MyBreakpointBehaviorComponent() {
96114

97115
### **Server Side Rendering**
98116

99-
*While serverside rendering is supported, it requires an explicit update via `useEffect` since viewport does not actually exist on the server before rendering to client. The following has been tested with [NextJS](https://nextjs.org/).*
117+
*Note: While serverside rendering is supported, it requires an explicit update via `useEffect` since viewport does not actually exist on the server before rendering to client. The following has been tested with [NextJS](https://nextjs.org/).*
100118

101-
*Sidenote that you will see a `useLayoutEffect` warning from React. This is perfectly normal as there is no viewport/context to paint to when pre-rendering in SSR and will not interfere with your app once served to the client*
119+
*Sidenote that you will see a `useLayoutEffect` warning from React. This is perfectly expected as there is no viewport/context to paint to when pre-rendering in SSR and will not interfere with your app once served to the client*
102120

103121
```js
104122
import React, { useLayoutEffect } from 'react'
105123
import useViewportSizes from 'use-viewport-sizes'
106124

107125
function MySSRComponent (props) {
108-
const [vpWidth, vpHeight, updateVpSizes] = useViewportSizes()
126+
const [vpW, vpH, updateVpSizes] = useViewportSizes();
109127

110128
// below, we add one post-render update
111129
// in order to register the client's viewport sizes
112130
// after serving SSR content
113131

114-
useEffect(()=> { updateVpSizes(); }, []);
132+
useEffect(()=> { updateVpSizes() }, []);
115133

116-
...renderLogic
134+
// ...renderLogic
117135
}
118136
```
119137

package-lock.json

Lines changed: 10 additions & 19 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "use-viewport-sizes",
3-
"version": "0.3.0-beta.0",
3+
"version": "0.3.0-beta.1",
44
"description": "a tiny React hook which allows you to track visible window viewport size in your components w/ an optional debounce or custom memo function for updates for optimal rendering.",
55
"main": "./build/index.js",
66
"types": "./build/index.d.ts",

0 commit comments

Comments
 (0)