st refs, which means that you can do this:

```ts
const { width, height } = useResizeObserver<HTMLDivElement>({
  ref: divElement,
});
```

## Using a Single Hook to Measure Multiple Refs

The hook reacts to ref changes, as it resolves it to an element to observe.
This means that you can freely change the custom `ref` option from one ref to
another and back, and the hook will start observing whatever is set in its options.

## Opting Out of (or Delaying) ResizeObserver Instantiation

In certain cases you might want to delay creating a ResizeObserver instance.

You might provide a library, that only optionally provides observation features
based on props, which means that while you have the hook within your component,
you might not want to actually initialise it.

Another example is that you might want to entirely opt out of initialising, when
you run some tests, where the environment does not provide the `ResizeObserver`.

([See discussions](https://github.com/ZeeCoder/use-resize-observer/issues/40))

You can do one of the following depending on your needs:

- Use the default `ref` RefCallback, or provide a custom ref conditionally,
  only when needed. The hook will not create a ResizeObserver instance up until
  there's something there to actually observe.
- Patch the test environment, and make a polyfill available as the ResizeObserver.
  (This assumes you don't already use the polyfilled version, which would switch
  to the polyfill when no native implementation was available.)

## The "onResize" Callback

By the default the hook will trigger a re-render on all changes to the target
element's width and / or height.

You can opt out of this behaviour, by providing an `onResize` callback function,
which'll simply receive the width and height of the element when it changes, so
that you can decide what to do with it:

```tsx
import React from "react";
import useResizeObserver from "use-resize-observer";

const App = () => {
  // width / height will not be returned here when the onResize callback is present
  const { ref } = useResizeObserver<HTMLDivElement>({
    onResize: ({ width, height }) => {
      // do something here.
    },
  });

  return <div ref={ref} />;
};
```

This callback also makes it possible to implement your own hooks that report only
what you need, for example:

- Reporting only width or height
- Throttle / debounce
- Wrap in `requestAnimationFrame`

## Hook Composition

As this hook intends to remain low-level, it is encouraged to build on top of it via hook composition, if additional features are required.

### Throttle / Debounce

You might want to receive values less frequently than changes actually occur.

[CodeSandbox Demo](https://codesandbox.io/s/use-resize-observer-throttle-and-debounce-8uvsg)

### Breakpoints

Another popular concept are breakpoints. Here is an example for a simple hook accomplishing that.

[CodeSandbox Demo](https://codesandbox.io/s/use-resize-observer-breakpoints-3hiv8)

## Defaults (SSR)

On initial mount the ResizeObserver will take a little time to report on the
actual size.

Until the hook receives the first measurement, it returns `undefined` for width
and height by default.

You can override this behaviour, which could be useful for SSR as well.

```ts
const { ref, width = 100, height = 50 } = useResizeObserver<HTMLDivElement>();
```

Here "width" and "height" will be 100 and 50 respectively, until the
ResizeObserver kicks in and reports the actual size.

## Without Defaults

If you only want real measurements (only values from the ResizeObserver without
any default values), then you can just leave defaults off:

```ts
const { ref, width, height } = useResizeObserver<HTMLDivElement>();
```

Here "width" and "height" will be undefined until the ResizeObserver takes its
first measurement.

## Container/Element Query with CSS-in-JS

It's possible to apply styles conditionally based on the width / height of an
element using a CSS-in-JS solution, which is the basic idea behind
container/element queries:

[CodeSandbox Demo](https://codesandbox.io/s/use-resize-observer-container-query-with-css-in-js-iitxl)

## Transpilation / Polyfilling

By default the library provides transpiled ES5 modules in CJS / ESM module formats.

Polyfilling is recommended to be done in the host app, and not within imported
libraries, as that way consumers have control over the exact polyfills being used.

That said, there's a [polyfilled](https://github.com/juggle/resize-observer)
CJS module that can be used for convenience:

```ts
import useResizeObserver from "use-resize-observer/polyfilled";
```

Note that using the above will use the polyfill, [even if the native ResizeObserver is available](https://github.com/juggle/resize-observer#basic-usage).

To use the polyfill as a fallback only when the native RO is unavailable, you can polyfill yourself instead,
either in your app's entry file, or you could create a local `useResizeObserver` module, like so:

```ts
// useResizeObserver.ts
import { ResizeObserver } from "@juggle/resize-observer";
import useResizeObserver from "use-resize-observer";

if (!window.ResizeObserver) {
  window.ResizeObserver = ResizeObserver;
}

export default useResizeObserver;
```

The same technique can also be used to provide any of your preferred ResizeObserver polyfills out there.

## Related

- [@zeecoder/container-query](https://github.com/ZeeCoder/container-query)
- [@zeecoder/react-resize-observer](https://github.com/ZeeCoder/react-resize-observer)

## License

MIT