CarlosEGuerraSilva
useBreakpoint hooks and tw-based components
Optimized SSR-friendly React hooks to get the current breakpoint based on:
- Viewport: uses
matchMediaand is global towindow. - Container (true per-element): uses
ResizeObserverto measure an element and return its breakpoint.
Includes condition helpers (largerThan/lessThan/onlyAt) and is tree-shakeable.
Installation
npm install react-tw-breakpointsPeer deps: React 18/19 (DOM).
Tailwind is NOT required for the hooks. If you use the experimental UI components (Container, Grid), Tailwind CSS is required and you must configure a safelist so their dynamic classes are included. See docs/guides/tailwind-safelist.md.
Documentation
Breakpoints
The library uses Tailwind-aligned breakpoints: xs (0px), sm (640px), md (768px), lg (1024px), xl (1280px), _2xl (1536px), and more.
Note:
- Hook/constant identifiers use a leading underscore for sizes starting with a number (e.g.
_2xl,_3xl) because TypeScript identifiers cannot start with digits. SeeBreakpointEnum. - Tailwind class names and component props use the native Tailwind form without underscore (e.g.
2xl). SeeGrid.
Scopes:
- Viewport breakpoints are defined up to
_5xl. SeeBREAKPOINT_ORDER. - Container breakpoints extend up to
_7xl. SeeCONTAINER_BREAKPOINT_ORDER.
Quick start
1) Viewport
import { useBreakpoint, useBreakpointCondition } from 'react-tw-breakpoints';
function Example() {
const bp = useBreakpoint(); // 'xs' | 'sm' | ...
const isLgUp = useBreakpointCondition({ largerThan: 'lg' });
const onlyMd = useBreakpointCondition({ onlyAt: 'md' });
return (
<div>
<p>Viewport BP: {bp}</p>
{isLgUp && <span>≥ lg</span>}
{onlyMd && <span>md only</span>}
</div>
);
}2) Container (true per-element)
import { useRef } from 'react';
import { useContainerBreakpoint } from 'react-tw-breakpoints';
function Card() {
const ref = useRef<HTMLDivElement>(null);
const bp = useContainerBreakpoint(ref); // based on the element width
return (
<div ref={ref} style={{ width: '100%' }}>
{bp === 'xs' && <OneCol />}
{bp === 'md' && <TwoCols />}
{bp === 'lg' && <ThreeCols />}
</div>
);
}API Overview
Hooks
useBreakpoint() - Returns the active viewport breakpoint label.
useBreakpointCondition(opts) - Evaluates viewport conditions (largerThan, lessThan, onlyAt).
useBreakpointContainer() - Container breakpoint set (viewport-based).
useContainerBreakpoint(ref) - True per-element breakpoint using ResizeObserver.
Helper Hooks: useBreakpointUp, useBreakpointDown, useBreakpointOnly, useBreakpointBetween
Helpers
getCurrentBreakpoint() - Synchronously get current breakpoint (SSR-safe).
getMediaQuery(query) - Get cached MediaQueryList for custom queries.
Components (Experimental)
[!CAUTION] These components are experimental and may change their API or functionality. They are subject to discussion and improvement proposals, so breaking changes or even removal may occur. Use them at your own risk.
There are some basic layout components to use in your application. These are independent of the hooks in this library, so they are not affected by changes to the API for hooks, helpers, etc.
Why?
Many UI libraries don't have basic layout components. You probably need something simple and straightforward like a <Container>, and you may not want to have to define it in every project you work on if you use the same UI library or another one that doesn't have one.
Container- Centered wrapper with max-width constraints.Grid- 12-column responsive grid system.
Quick Examples
Responsive Navigation
import { useBreakpointCondition } from 'react-tw-breakpoints';
function Navigation() {
const isMobile = useBreakpointCondition({ lessThan: 'lg' });
return <nav>{isMobile ? <MobileMenu /> : <DesktopMenu />}</nav>;
}Adaptive Card
import { useRef } from 'react';
import { useContainerBreakpoint } from 'react-tw-breakpoints';
function Card() {
const cardRef = useRef<HTMLDivElement>(null);
const breakpoint = useContainerBreakpoint(cardRef);
return (
<div ref={cardRef}>
{breakpoint === 'xs' && <CompactLayout />}
{breakpoint === 'lg' && <ExpandedLayout />}
</div>
);
}Advanced Topics
CSS @container Queries
For style-based container queries without JavaScript, use native CSS @container. Learn more.
SSR and StrictMode
Hooks use useSyncExternalStore for safe subscriptions. In SSR they return base values (xs or false) and hydrate on the client. No duplicate listeners in StrictMode.
Browser Compatibility
matchMedia: All modern browsersResizeObserver: Chrome/Edge 64+, Safari 13.1+, Firefox 69+- CSS
@container: Chrome/Edge 105+, Safari 16+, Firefox 110+
FAQ
Why two kinds of “container breakpoints”?
useBreakpointContaineruses viewport with a different label set (useful if you want two global grids).useContainerBreakpointis true per element.
Can I change breakpoints?
- Yes, edit
src/const/breakpoints.tsand rebuild the package.
- Yes, edit
Tree‑shaking?
- Yes.
package.jsonexports ESM withsideEffects: false. Import only what you use.
- Yes.
Want to contribute?
Please read the contribution guidelines first.