Responsive Props Without Media Queries: Chakra UI's useBreakpointValue Hook

The Problem: Repeating Breakpoint Logic Across Components

Building responsive UIs often means writing the same media query logic over and over. A card needs width: 100% on mobile, 50% on tablet, 33% on desktop. Padding, font sizes, and gap values follow the same pattern. Teams end up with scattered @media blocks, verbose style objects, or custom hooks that each reimplement breakpoint matching.

Chakra UI's useBreakpointValue hook solves this by centralizing responsive value selection. It returns the correct value for the current screen width using the theme's breakpoints, so component props adapt without manual media queries.

How the Hook Works

useBreakpointValue accepts an object whose keys are breakpoint names defined in your Chakra UI theme (typically base, sm, md, lg, xl, 2xl). It internally uses useMediaQuery to detect the active breakpoint and returns the matching value. If the current width falls between breakpoints, the nearest smaller key wins — base is the fallback.

The hook requires a ChakraProvider (or BreakpointProvider) ancestor. Without it, the hook returns the base value, which can cause silent layout issues if you're rendering outside a Chakra-wrapped app or using a custom theme that omits breakpoints.

Worked Example: Responsive Card Component

Here's a Card that adjusts its width and padding across breakpoints using a single hook call:

import { Box, useBreakpointValue } from '@chakra-ui/react'

export function ResponsiveCard({ children }) {
  const width = useBreakpointValue({
    base: '100%',
    sm: '100%',
    md: '50%',
    lg: '33.333%',
    xl: '25%'
  })

  const padding = useBreakpointValue({
    base: 4,
    md: 6,
    lg: 8
  })

  return (
    
      {children}
    
  )
}

Resize the browser and the card reflows at each breakpoint — no @media rules, no array syntax in style props. The values stay co-located with the component, making maintenance straightforward.

Trade-offs and Limitations

• Provider dependency: The hook only works inside a Chakra UI provider. If you render a component in a portal, a non-Chakra micro-frontend, or a test environment without the provider, you'll get the base value.
• Theme coupling: Changing or removing breakpoints in theme.breakpoints without updating the hook's keys causes silent failures — the hook won't warn you.
• JavaScript recalculation: Every resize triggers a re-render. For simple layout shifts (grid columns, flex wrapping), CSS Grid or Flexbox with container queries is lighter weight. Reserve the hook for values that genuinely need JavaScript — dynamic widths, conditional rendering, or prop drilling to non-Chakra children.

Actionable Next Steps

1. Audit your codebase for repeated responsive prop patterns — width, padding, fontSize, gap, column counts.
2. Replace one cluster with useBreakpointValue and verify the breakpoint transitions in browser devtools (toggle device toolbar).
3. Add a visual regression test (e.g., Chromatic, Percy) that captures the component at each breakpoint to catch theme changes early.
4. Document your theme's breakpoint names in a shared location so the hook's keys stay in sync.

Start small, measure the reduction in duplicated media query logic, and expand where the hook pays off.