Documentation
useBreakpoint

useBreakpoint

useBreakpoint returns the current breakpoint of a element, contains useful utilities to work with user-defined breakpoints and automatically triggers callback when the element's size is equal to a specific breakpoint.

Install

To start using useBreakpoint, you can install the @react-awesome/use-breakpoint library or you can import it directly from @react-awesome/components if you have installed it before. In your project directory, run the following command to install the dependencies:

npm i @react-awesome/use-breakpoint

Usage

By default, useBreakpoint has the same breakpoint configs with TailwindCSS (opens in a new tab). But you can freely use any configs that best suit your case.

import { useBreakpoint } from '@react-awesome/use-breakpoint'
 
const Example = () => {
  const ref = useRef(null)
 
  const { currentBreakpoint } = useBreakpoint({
    containerEl: ref.current,
  })
 
  return (
    <div ref={ref}>
      <div>{currentBreakpoint}</div>
    </div>
  )
}

Custom breakpoint configs

import { useBreakpoint } from '@react-awesome/use-breakpoint'
 
const Example = () => {
  const ref = useRef(null)
 
  const { currentBreakpoint } = useBreakpoint({
    containerEl: ref.current,
    breakpoints: {
      '📱': 320,
      '💻': 480,
      '🖥️': 640,
    },
  })
 
  return (
    <div ref={ref}>
      <div>{currentBreakpoint}</div>
    </div>
  )
}

Breakpoint utilities

useBreakpoint returns some utilities to assert with the current container's size:

  • smaller
  • greater
  • smallerOrEqual
  • greaterOrEqual
  • between

Shrink the container to see the alien!

import { useBreakpoint } from '@react-awesome/use-breakpoint'
 
const Example = () => {
  const ref = useRef(null)
 
  const { smaller } = useBreakpoint({
    containerEl: ref.current,
  })
 
  return (
    <div ref={setRef}>
      <p>Shrink the container to see the alien!</p>
      <p>{smaller('md') && '👽'}</p>
    </div>
  )
}

Callbacks

useBreakpoint also supports to trigger provided callback on a specific breakpoint.

The background will change when container's size is changed

import { useBreakpoint } from '@react-awesome/use-breakpoint'
 
const Example = () => {
  const ref = useRef(null)
  const [background, setBg] = useState('red')
 
  useBreakpoint({
    containerEl: ref,
    breakpoints: {
      sm: 320,
      md: 480,
      lg: 640,
    },
    callbacks: {
      sm: () => setBg('red'),
      md: () => setBg('green'),
      lg: () => setBg('blue'),
    },
  })
 
  return (
    <>
      <div ref={ref}>
        <p> The background will change when container's size is changed</p>
      </div>
      <div
        style={{
          background,
        }}
      />
    </>
  )
}

Parameters

The useBreakpoint takes the following parameters:

Options

  • Type: UseBreakpointOpts

API

containerEl

  • Type: HTMLElement
  • Default: window.document.body

currentBreakpoint

  • Type: string

smaller

  • Type: (breakpoint: string) => boolean

smallerOrEqual

  • Type: (breakpoint: string) => boolean

greater

  • Type: (breakpoint: string) => boolean

greaterOrEqual

  • Type: (breakpoint: string) => boolean

between

  • Type: (breakpoint: string) => boolean

Types

UseBreakpointOpts

breakpoints
  • Type: Record<string, number>
callbacks
  • Type: Record<string, () => void>
fallbackValue
  • Type: string
usePrevioususeClickOutside