0
# React Measure
1
2
React Measure is a React component library for computing and tracking DOM element measurements using the ResizeObserver API. It provides both a Measure component and a withContentRect higher-order component that enable developers to track and respond to size changes in React components.
3
4
## Package Information
5
6
- **Package Name**: react-measure
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install react-measure` or `yarn add react-measure`
10
11
## Core Imports
12
13
```javascript
14
import Measure from 'react-measure';
15
import { withContentRect } from 'react-measure';
16
```
17
18
For CommonJS:
19
20
```javascript
21
const Measure = require('react-measure').default;
22
const { withContentRect } = require('react-measure');
23
```
24
25
## Basic Usage
26
27
```javascript
28
import React, { Component } from 'react';
29
import Measure from 'react-measure';
30
31
class ResponsiveComponent extends Component {
32
state = {
33
dimensions: { width: -1, height: -1 }
34
};
35
36
render() {
37
const { width, height } = this.state.dimensions;
38
39
return (
40
<Measure
41
bounds
42
onResize={contentRect => {
43
this.setState({ dimensions: contentRect.bounds });
44
}}
45
>
46
{({ measureRef }) => (
47
<div ref={measureRef}>
48
<p>Width: {width}px, Height: {height}px</p>
49
{width > 500 && <p>Wide layout content</p>}
50
</div>
51
)}
52
</Measure>
53
);
54
}
55
}
56
```
57
58
## Architecture
59
60
React Measure is built around several key components:
61
62
- **ResizeObserver Integration**: Uses native ResizeObserver API with polyfill fallback for cross-browser compatibility
63
- **Render Props Pattern**: Measure component uses children-as-function for flexible rendering
64
- **HOC Pattern**: withContentRect provides an alternative Higher-Order Component API
65
- **Measurement Types**: Supports five types of measurements (client, offset, scroll, bounds, margin)
66
- **Performance Optimization**: Uses requestAnimationFrame for batched DOM updates
67
68
## Capabilities
69
70
### Measure Component
71
72
Core component that wraps children and provides measurement capabilities via render props pattern. Handles ResizeObserver lifecycle and provides measurement data through a children function.
73
74
```javascript { .api }
75
/**
76
* React component that provides element measurement capabilities via render props
77
* @param {Object} props - Component props
78
* @param {boolean} [props.client] - Include client measurements
79
* @param {boolean} [props.offset] - Include offset measurements
80
* @param {boolean} [props.scroll] - Include scroll measurements
81
* @param {boolean} [props.bounds] - Include bounds measurements
82
* @param {boolean} [props.margin] - Include margin measurements
83
* @param {Object|Function} [props.innerRef] - Ref to access internal element
84
* @param {Function} [props.onResize] - Callback when dimensions change
85
* @param {Function} props.children - Render prop function
86
* @returns {React.ReactElement}
87
*/
88
function Measure(props);
89
90
// Render prop function receives:
91
// {
92
// measureRef: function - Must be passed to measured element as ref
93
// measure: function - Programmatically trigger measurement
94
// contentRect: object - Current measurements
95
// }
96
```
97
98
[Measure Component](./measure-component.md)
99
100
### withContentRect HOC
101
102
Higher-order component that provides measurement functionality to wrapped components. Accepts measurement types as configuration and injects measurement data as props.
103
104
```javascript { .api }
105
/**
106
* Higher-order component that provides measurement functionality
107
* @param {string|string[]} [types] - Measurement types: 'client', 'offset', 'scroll', 'bounds', 'margin'
108
* @returns {Function} - Function that accepts a component and returns wrapped component
109
*/
110
function withContentRect(types);
111
112
// Returns function that wraps components with measurement props:
113
// - measureRef: function to attach to measured element
114
// - measure: function to programmatically measure
115
// - contentRect: object with current measurements
116
// Plus all original Measure component props are available
117
```
118
119
[Higher-Order Component](./with-content-rect.md)
120
121
## Types
122
123
```javascript { .api }
124
// contentRect object structure returned by measurements
125
const contentRect = {
126
// ResizeObserver entry (when available)
127
entry: {
128
width: 0, // number
129
height: 0, // number
130
top: 0, // number
131
left: 0, // number
132
bottom: 0, // number
133
right: 0 // number
134
},
135
136
// Client measurements (when client: true)
137
client: {
138
top: 0, // number - clientTop
139
left: 0, // number - clientLeft
140
width: 0, // number - clientWidth
141
height: 0 // number - clientHeight
142
},
143
144
// Offset measurements (when offset: true)
145
offset: {
146
top: 0, // number - offsetTop
147
left: 0, // number - offsetLeft
148
width: 0, // number - offsetWidth
149
height: 0 // number - offsetHeight
150
},
151
152
// Scroll measurements (when scroll: true)
153
scroll: {
154
top: 0, // number - scrollTop
155
left: 0, // number - scrollLeft
156
width: 0, // number - scrollWidth
157
height: 0 // number - scrollHeight
158
},
159
160
// Bounds measurements (when bounds: true)
161
bounds: {
162
top: 0, // number - from getBoundingClientRect()
163
right: 0, // number
164
bottom: 0, // number
165
left: 0, // number
166
width: 0, // number
167
height: 0 // number
168
},
169
170
// Margin measurements (when margin: true)
171
margin: {
172
top: 0, // number - from getComputedStyle()
173
right: 0, // number
174
bottom: 0, // number
175
left: 0 // number
176
}
177
};
178
```