@decisiv/breakpoint-observer v1.8.8

BreakpointObserver

• Introduction
• Usage
  • Installation
  • React Component
  • React hook
• How it works

Introduction

This package provides both a React hook and React component that observe a DOM element and enable component based responsiveness (vs. page based). The underlying technology is the react-hook-size package, a hook based implementation of the experimental ResizeObserver technology. Because browser adoption is still relatively sparse, a polyfill is included.

Usage

Installation

yarn add @decisiv/breakpoint-observer

React Component

The BreakpointObserver component is built with the function as a child pattern. The children prop is required and must be a function.

import BreakpointObserver, { sizes } from '@decisiv/breakpoint-observer';

function ExampleComponent() {
  // The breakpoints object defines the minimum widths for specific breakpoint names.
  const breakpoints = {
    [sizes.SM]: 300,
    [sizes.MD]: 420,
    [sizes.LG]: 560,
  };

  return (
    <BreakpointObserver
      // This prop is optional, but if undefined the returned `breakpoint` will also be undefined.
      breakpoints={breakpoints}
    >
      {({
        breakpoint, // The currently active breakpoint. Defaults to `sizes.XS`.
        dimensions, // An object containing the `height` & `width` of the observed DOM element.
        observedElementRef, // The ref must be assigned to the DOM element you want to observe.
      }) => (
        <div id="the-observed-html-element" ref={observedElementRef}>
          <YourStyledComponentWithModifiers
            modifiers={{
              [sizes.XS]: 'hidden',
              [sizes.SM]: 'small',
              [sizes.MD]: 'medium',
              [sizes.LG]: 'large',
            }}
            size={breakpoint}
          />
        </div>
      )}
    </BreakpointObserver>
  );
}

Props

React hook

The hook provides a very similar API to the React component. The primary advantage is that it can be used outside of the render statement of the component you are building.

import { sizes, useBreakpointObserver } from '@decisiv/breakpoint-observer';

function ExampleComponent() {
  // The breakpoints object defines the minimum widths for specific breakpoint names.
  const breakpoints = {
    [sizes.SM]: 300,
    [sizes.MD]: 420,
    [sizes.LG]: 560,
  };

  const [
    observedElementRef, // The ref must be assigned to the DOM element you want to observe.
    {
      breakpoint, // The currently active breakpoint. Defaults to `sizes.XS`.
      dimensions, // An object containing the `height` & `width` of the observed DOM element.
    },
  ] = useBreakpointObserver(
    breakpoints, // Optional, but if undefined the returned `breakpoint` will also be undefined.
  );

  return (
    <div id="the-observed-html-element" ref={observedElementRef}>
      <YourStyledComponentWithModifiers
        modifiers={{
          [sizes.XS]: 'hidden',
          [sizes.SM]: 'small',
          [sizes.MD]: 'medium',
          [sizes.LG]: 'large',
        }}
        size={breakpoint}
      />
    </div>
  );
}

How it works

Both the hook and component utilities will create and listen to a ResizeObserver for an HTML element. You must tell the utilities which HTML element to observe using the observedElementRef. Once registered and rendered, both utilities give you access to the current dimensions (height and width) and the currently active breakpoint.

The logic used to select the currently active breakpoint is relatively simple. The number values in the breakpoints prop are considered minimum widths. The utilities will compare those minimum widths to the HTML element's actual width and select the breakpoint with the largest minimum width that is less than or equal to the components actual width.

There is no need to define a breakpoint with a minimum width of zero. The utilities assume a breakpoint of sizes.XS exists with a minimum width of zero. If the width is less than the smallest declared breakpoint minimum width, the breakpoint value passed down will be sizes.XS.