react-tw-breakpoints - npm explorer

useBreakpoint hooks and tw-based components

![Ask DeepWiki](https://deepwiki.com/CarlosEGuerraSilva/react-tw-breakpoints)

Optimized SSR-friendly React hooks to get the current breakpoint based on:

- Viewport: uses matchMedia and is global to window.
- Container (true per-element): uses ResizeObserver to measure an element and return its breakpoint.

Includes condition helpers (largerThan/lessThan/onlyAt) and is tree-shakeable.

Installation

sh

npm install react-tw-breakpoints





Peer 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



- API Reference

  - Hooks

  - Helpers

  - Components

- Guides

  - Tailwind Safelist Configuration

  - CSS Container Queries

  - SSR and Hydration

- Examples

  - Viewport Hooks

  - Container Hooks

  - Components



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. See BreakpointEnum

.

- Tailwind class names and component props use the native Tailwind form without underscore (e.g.

2xl). See Grid

.



Scopes:



- Viewport breakpoints are defined up to

_5xl. See BREAKPOINT_ORDER

.

- Container breakpoints extend up to

_7xl. See CONTAINER_BREAKPOINT_ORDER

.



Quick start



$3

tsx

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 (

    

      Viewport BP: {bp}

      {isLgUp && ≥ lg}

      {onlyMd && md only}

    

  );

}

$3

tsx

import { useRef } from 'react';

import { useContainerBreakpoint } from 'react-tw-breakpoints';



function Card() {

  const ref = useRef(null);

  const bp = useContainerBreakpoint(ref); // based on the element width

  return (

    

      {bp === 'xs' && }

      {bp === 'md' && }

      {bp === 'lg' && }

    

  );

}





API Overview



$3

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





Hooks API Reference



$3

getCurrentBreakpoint()

 - Synchronously get current breakpoint (SSR-safe).

getMediaQuery(query) - Get cached MediaQueryList

 for custom queries.



Helpers API Reference



$3



> [!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.



$3



Many UI libraries don't have basic layout components. You probably need something simple and straightforward like a

, 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.



Components API Reference



Quick Examples



$3

tsx

import { useBreakpointCondition } from 'react-tw-breakpoints';



function Navigation() {

  const isMobile = useBreakpointCondition({ lessThan: 'lg' });



  return {isMobile ?  : };

}

$3

tsx

import { useRef } from 'react';

import { useContainerBreakpoint } from 'react-tw-breakpoints';



function Card() {

  const cardRef = useRef(null);

  const breakpoint = useContainerBreakpoint(cardRef);



  return (

    

      {breakpoint === 'xs' && }

      {breakpoint === 'lg' && }

    

  );

}





📚 More Examples



Advanced Topics



$3



For style-based container queries without JavaScript, use native CSS

@container

. Learn more.



$3



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.



$3



-

matchMedia

: All modern browsers

-

ResizeObserver

: Chrome/Edge 64+, Safari 13.1+, Firefox 69+

- CSS

@container

: Chrome/Edge 105+, Safari 16+, Firefox 110+



FAQ



- Why two kinds of “container breakpoints”?

  -

useBreakpointContainer

 uses viewport with a different label set (useful if you want two global grids).

  -

useContainerBreakpoint

 is true per element.



- Can I change breakpoints?

  - Yes, edit

src/const/breakpoints.ts

 and rebuild the package.



- Tree‑shaking?

  - Yes.

package.json exports ESM with sideEffects: false`. Import only what you use.

Want to contribute?

Please read the contribution guidelines first.

License

MIT

!assets/project.svg

useBreakpoint hooks and tw-based components

![Ask DeepWiki](https://deepwiki.com/CarlosEGuerraSilva/react-tw-breakpoints)

Installation

sh

npm install react-tw-breakpoints





Peer 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



- API Reference

  - Hooks

  - Helpers

  - Components

- Guides

  - Tailwind Safelist Configuration

  - CSS Container Queries

  - SSR and Hydration

- Examples

  - Viewport Hooks

  - Container Hooks

  - Components



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. See BreakpointEnum

.

- Tailwind class names and component props use the native Tailwind form without underscore (e.g.

2xl). See Grid

.



Scopes:



- Viewport breakpoints are defined up to

_5xl. See BREAKPOINT_ORDER

.

- Container breakpoints extend up to

_7xl. See CONTAINER_BREAKPOINT_ORDER

.



Quick start



$3

tsx

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 (

    

      Viewport BP: {bp}

      {isLgUp && ≥ lg}

      {onlyMd && md only}

    

  );

}

$3

tsx

import { useRef } from 'react';

import { useContainerBreakpoint } from 'react-tw-breakpoints';



function Card() {

  const ref = useRef(null);

  const bp = useContainerBreakpoint(ref); // based on the element width

  return (

    

      {bp === 'xs' && }

      {bp === 'md' && }

      {bp === 'lg' && }

    

  );

}





API Overview



$3

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





Hooks API Reference



$3

getCurrentBreakpoint()

 - Synchronously get current breakpoint (SSR-safe).

getMediaQuery(query) - Get cached MediaQueryList

 for custom queries.



Helpers API Reference



$3



> [!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.



$3



Many UI libraries don't have basic layout components. You probably need something simple and straightforward like a

, 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.



Components API Reference



Quick Examples



$3

tsx

import { useBreakpointCondition } from 'react-tw-breakpoints';



function Navigation() {

  const isMobile = useBreakpointCondition({ lessThan: 'lg' });



  return {isMobile ?  : };

}

$3

tsx

import { useRef } from 'react';

import { useContainerBreakpoint } from 'react-tw-breakpoints';



function Card() {

  const cardRef = useRef(null);

  const breakpoint = useContainerBreakpoint(cardRef);



  return (

    

      {breakpoint === 'xs' && }

      {breakpoint === 'lg' && }

    

  );

}





📚 More Examples



Advanced Topics



$3



For style-based container queries without JavaScript, use native CSS

@container

. Learn more.



$3



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.



$3



-

matchMedia

: All modern browsers

-

ResizeObserver

: Chrome/Edge 64+, Safari 13.1+, Firefox 69+

- CSS

@container

: Chrome/Edge 105+, Safari 16+, Firefox 110+



FAQ



- Why two kinds of “container breakpoints”?

  -

useBreakpointContainer

 uses viewport with a different label set (useful if you want two global grids).

  -

useContainerBreakpoint

 is true per element.



- Can I change breakpoints?

  - Yes, edit

src/const/breakpoints.ts

 and rebuild the package.



- Tree‑shaking?

  - Yes.

package.json exports ESM with sideEffects: false`. Import only what you use.

Want to contribute?

Please read the contribution guidelines first.

License

MIT