React Breakpoints

react-breakpoints allows you to respond to changes in a DOM element's size. You can change the evaluated logic and rendered output of components based on observed size changes in DOM elements. For example, you can change a dropdown menu to a horizontal list menu based on its parent container's width without using CSS media queries.

📦 What's in the box?

No polling. No event listening. No sentinel elements. Just a ResizeObserver!

This package provides you with:

• a <Provider> to instantiate the ResizeObserver;
• an <Observe> component to observe changes in a DOM element and respond to them.

For power users this package also provides:

• a useBreakpoints() hook to change a component's behaviour based on the observed size information in the nearest parent <Observe>;
• a useResizeObserver() hook to connect a DOM element in your component to the instantiated ResizeObserver on <Provider>;
• a useResizeObserverEntry() hook to retrieve the ResizeObserverEntry put on the nearest <Context>. This is what useBreakpoints() uses under the hood.

🚧 Developer status

Several projects within Envato are currently using this package, giving me confidence that the API is clear and the code adds value. The package is still in an early stage, but exposure to "the wild" will help reveal more edge-cases and hopefully make the package more robust overall.

⚡️ Quick start

Follow these minimum required steps to get started with react-breakpoints. This is just the tip of the iceberg, though. Check the API Docs for all options.

npm install @envato/react-breakpoints

Set up the provider

import { Provider as ResizeObserverProvider } from '@envato/react-breakpoints';

const App = () => (
  <ResizeObserverProvider>
    ...
  </ResizeObserverProvider>
)

⚠️ Caution — You may need to pass some props to <Provider> to increase browser support. Please refer to the API Docs.

Observe an element

Everything you render through <Observe> has access to the size of the element that is given {...observedElementProps}. This is called the "Observe Scope".

import { Observe } from '@envato/react-breakpoints';

const MyObservingComponent = () => (
  <Observe
    breakpoints={{
      widths: {
        0: 'mobile',
        769: 'tablet',
        1025: 'desktop'
      }
    }}
    render={({ observedElementProps, widthMatch = 'ssr' }) => (
      <div {...observedElementProps}>
        <div className={widthMatch}>
      </div>
    )}
  />
);

See the API Docs for reference guides and usage examples.

Observing vs. Consuming boxes

There is an important distinction between the box you observe and the box you consume for triggering breakpoints. See Observing vs. Consuming Boxes for more information.

Re-rendering

Using useResizeObserver(), useResizeObserverEntry() or useBreakpoints() in your components causes them to re-render every time a resize is observed.

In some cases, you may want to optimise this. If you only want to re-render your components when breakpoint values actually change, use React.useMemo or React.memo.

Server-Side Rendering

See Server-Side Rendering for more information.

Maintainers

• Marc Dingena (owner)

Contributing

For bug fixes, documentation changes, and small features:

1. Fork this repository.
2. Create your feature branch (git checkout -b my-new-feature).
3. Commit your changes (git commit -am 'Add some feature').
4. Push to the branch (git push origin my-new-feature).
5. Create a new Pull Request.

For larger new features: Do everything as above, but first also make contact with the project maintainers to be sure your change fits with the project direction and you won't be wasting effort going in the wrong direction.