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.

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;
• a useBreakpoints() hook to change a component's behaviour based on the observed size information in the nearest parent <Observe>.

For power users this package also provides:

• a <Context> on which you can assign a ResizeObserverEntry value to update any nested components that are using useBreakpoints();
• 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.

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.

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

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.

Everything you render through <Observe> becomes aware of the size of the element that is given {...observedElementProps}. This is called an "Observe Scope".

import { Observe } from '@envato/react-breakpoints'; const MyObservingComponent = () => ( <Observe render={({ observedElementProps }) => ( <aside {...observedElementProps}> <MyResponsiveComponent /> </aside> )} /> );

Components that are rendered within the "Observe Scope" can consume observation results via useBreakpoints():

import { useBreakpoints } from '@envato/react-breakpoints'; const MyResponsiveComponent = () => { const options = { widths: { 0: 'mobile', 769: 'tablet', 1025: 'desktop' } }; const [label] = useBreakpoints(options); return <div className={label}>This element is currently within the {label} range.</div>; };

However, <Observe> supports additional props allowing you to observe and consume observations — no useBreakpoints() required!

See the API Docs for reference guides and usage examples.

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.

See Server-Side Rendering for more information.

• Marc Dingena (owner)

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.