{ observe(el); // Set the target element for measuring ref.current = el; // Share the element for other purposes }} /> ); }; ``` ## Performance Optimization The `onResize` event will be triggered whenever the size of the target element is changed. We can reduce the frequency of the event callback by activating the [responsive mode](#responsive-components) or implementing our own throttled/debounced function as below. Note that in order to throttle/debounce the function correctly, it will need to be memorized else it will be recreated on every render call. ```js import { useMemo } from "react"; import _ from "lodash"; const returnObj = useDimensions({ onResize: useMemo( () => _.throttle(() => { // Triggered once per every 500 milliseconds }, 500), [] ), }); ``` ## Working in TypeScript This hook supports [TypeScript](https://www.typescriptlang.org), you can tell the hook what type of element you are going to observe through the [generic type](https://www.typescriptlang.org/docs/handbook/generics.html): ```ts const App = () => { const { observe } = useDimensions(); return

; }; ``` > 💡 For more available types, please [check it out](src/react-cool-dimensions.d.ts). ## API ```js const returnObj = useDimensions(options?: object); ``` ### Return object It's returned with the following properties. | Key | Type | Default | Description | | ------------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | | `observe` | function | | To set a target element for measuring or re-start observing the current target element. | | `unobserve` | function | | To stop observing the current target element. | | `width` | number or null | null | The width of the target element in pixel. Null while target has not mounted. | | `height` | number or null | null | The height of the target element in pixel. Null while target has not mounted.Z | | `currentBreakpoint` | string | | Indicates the current breakpoint of the [responsive components](#responsive-components). | | `entry` | object | | The [ResizeObserverEntry](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) of the target element. | ### Parameter The `options` provides the following configurations and event callback for you. | Key | Type | Default | Description | | -------------------------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `breakpoints` | object | | Activates the responsive mode for [responsive components](#responsive-components) or [performance optimization](#performance-optimization). | | `updateOnBreakpointChange` | boolean | `false` | Tells the hook to update the state on breakpoint changed. | | `useBorderBoxSize` | boolean | `false` | Tells the hook to [measure the target element based on the border-box size](#border-box-size-measurement). | | `shouldUpdate` | function | | Tells the hook to [conditionally update the state](#conditionally-updating-state). | | `onResize` | function | | It's invoked whenever the size of the target element is changed. But in [responsive mode](#responsive-components), it's invoked based on the changing of the breakpoint rather than the size. | | `polyfill` | ResizeObserver | | It's used for [injecting a polyfill](#resizeobserver-polyfill). | ## ResizeObserver Polyfill [ResizeObserver has good support amongst browsers](https://caniuse.com/?search=ResizeObserver), but it's not universal. You'll need to use polyfill for browsers that don't support it. Polyfills is something you should do consciously at the application level. Therefore `react-cool-dimensions` doesn't include it. We recommend using [@juggle/resize-observer](https://github.com/juggle/resize-observer): ```sh $ yarn add @juggle/resize-observer # or $ npm install --save @juggle/resize-observer ``` Then inject it by the `polyfill` option: ```js import { ResizeObserver } from "@juggle/resize-observer"; const { width, height } = useDimensions(ref, { polyfill: ResizeObserver }); ``` Or pollute the `window` object: ```js import { ResizeObserver, ResizeObserverEntry } from "@juggle/resize-observer"; if (!("ResizeObserver" in window)) { window.ResizeObserver = ResizeObserver; // Only use it when you have this trouble: https://github.com/wellyshen/react-cool-dimensions/issues/45 // window.ResizeObserverEntry = ResizeObserverEntry; } ``` You could use dynamic imports to only load the file when the polyfill is required: ```js (async () => { if (!("ResizeObserver" in window)) { const module = await import("@juggle/resize-observer"); window.ResizeObserver = module.ResizeObserver; // Only use it when you have this trouble: https://github.com/wellyshen/react-cool-dimensions/issues/45 // window.ResizeObserverEntry = module.ResizeObserverEntry; } })(); ``` ## Articles / Blog Posts > 💡 If you have written any blog post or article about `react-cool-dimensions`, please open a PR to add it here. - Featured on [React Status #191](https://react.statuscode.com/issues/191). ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

_Welly
💻 📖 🚧

_{Runar Kristoffersen}
📖 💻 🤔

_{Ricardo Amaral}
💻

_Cornelius
🐛

_{Joseph Horton}
📖

_sirkrisp
💻

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!