useBreakpoints

Reactive viewport breakpoints

useBreakpoints takes a map of breakpoint names to minimum widths in pixels and tells you which ones the viewport has reached. It subscribes to one pair of window.matchMedia() queries per breakpoint, so the component re-renders only when the viewport crosses a breakpoint, not on every resize. Each breakpoint name is true once the viewport is at least that wide, and greater, greaterOrEqual, smaller, smallerOrEqual and between compare against any of them. current lists every breakpoint reached, and active is the largest of them.

When to Use

Switching layouts in JavaScript, such as a drawer on mobile and a sidebar on desktop
Keeping JavaScript logic in step with CSS breakpoints, for example breakpointsTailwind to match Tailwind’s sm to 2xl
Changing the number of columns or items with the screen size

Notes

SSR-safe: on the server and during hydration the hook assumes a viewport defaultWidth pixels wide (default 0), then switches to the real width after hydration without a mismatch.
Mobile first: breakpoints are minimum widths. between(a, b) is true from a up to, but not including, b.
Inline objects are fine: the hook keys its subscriptions on the breakpoint values, so passing a new object each render does not resubscribe.
Related hooks: for a single arbitrary query, use useMediaQuery.

Usage

Live Editor

function Demo() {
  const bp = useBreakpoints(breakpointsTailwind);

  return (
    <div>
      <div>Active breakpoint: {bp.active ?? "below sm"}</div>
      <div>Reached: {bp.current.join(", ") || "none"}</div>
      <div>Smaller than md: {bp.smaller("md") ? "Yes" : "No"}</div>
      <div>Between md and xl: {bp.between("md", "xl") ? "Yes" : "No"}</div>
    </div>
  );
};

Result

API

Breakpoints

UseBreakpointsOptions

Property	Description	Type	DefaultValue
defaultWidth	The viewport width, in pixels, assumed on the server and during hydration. Use it to render the layout most of your visitors will see.	number	`0`

UseBreakpointsReturn

Property	Description	Type	DefaultValue
greaterOrEqual	Whether the viewport is at least as wide as the breakpoint	(k: K) => boolean (Required)	`-`
greater	Whether the viewport is wider than the breakpoint	(k: K) => boolean (Required)	`-`
smaller	Whether the viewport is narrower than the breakpoint	(k: K) => boolean (Required)	`-`
smallerOrEqual	Whether the viewport is at most as wide as the breakpoint	(k: K) => boolean (Required)	`-`
between	Whether the viewport is at least as wide as `a` and narrower than `b`	(a: K, b: K) => boolean (Required)	`-`
current	Every breakpoint the viewport has reached, from smallest to largest	K[] (Required)	`-`
active	The largest breakpoint the viewport has reached, or undefined below the smallest one	K \| undefined (Required)	`-`

useBreakpoints

Returns

UseBreakpointsReturn<K>: A boolean per breakpoint (true once the viewport is at least that wide), comparison helpers, and the current and active breakpoints

Arguments

Argument	Description	Type	DefaultValue
breakpoints	A map from breakpoint name to its minimum viewport width in pixels	Breakpoints<K> (Required)	-
options	Options	UseBreakpointsOptions \| undefined	-