Harnessing Chakra UI’s `useBreakpointValue` for Responsive React Components

Why `useBreakpointValue` Solves a Real‑World Problem

When building a React app with Chakra UI, you often need to change component behavior based on the viewport size. The traditional approach is to write media queries in CSS or to query window.innerWidth manually and branch logic in JavaScript. Both methods scatter breakpoint logic across the codebase and make it hard to keep styles and behavior in sync.

Chakra’s useBreakpointValue hook lets you declare a mapping of breakpoint names to any JavaScript value—string, number, object, or even a React element—and returns the value that matches the current viewport. The hook watches the window size, updates automatically, and pulls breakpoint definitions from the theme, keeping your layout logic consistent with your design system.

How It Works Under the Hood

The hook internally uses Chakra’s useMediaQuery implementation. On the client, it subscribes to the resize event and recomputes the active breakpoint. On the server, it has no window object, so it returns undefined unless you provide a defaultValue or fallbackValue. The returned value is memoized per render, so it only triggers a re‑render when the breakpoint changes.

Practical Example: Responsive Flex Direction

Below is a minimal component that changes the flex direction of a box between a column on small screens and a row on medium and larger screens. It also logs the current breakpoint value to the console so you can see the hook in action.

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

export const ResponsiveFlex = () => {
  const flexDir = useBreakpointValue({ base: "column", md: "row" });
  console.log("Current flex direction:", flexDir);

  return (
    <Box display="flex" flexDirection={flexDir} p={4} bg="gray.100">
      <Box flex="1" bg="teal.200">Item 1</Box>
      <Box flex="1" bg="teal.300">Item 2</Box>
    </Box>
  );
};

Running this component in a browser will show the two items stacked vertically when the viewport width is below the md breakpoint (768 px by default). When you widen the window beyond that point, the items shift side‑by‑side automatically.

Trade‑Offs and Limitations

• Server‑Side Rendering (SSR): Because useBreakpointValue relies on window, it returns undefined during SSR. If your component needs a value on initial render, supply a defaultValue or fallbackValue.
• Performance: Each resize event triggers a re‑render of any component using the hook. In highly dynamic UIs, consider memoizing the component or debouncing resize handling.
• Theme Coupling: The hook uses the theme’s breakpoint keys. If you rename or add breakpoints, update any hard‑coded mapping objects to avoid mismatches.
• Complex Values: While you can return objects, remember that React will re‑create the object on every breakpoint change, which may cause unnecessary re‑renders downstream. Wrap complex values in useMemo if needed.

Actionable Checklist for Production Use

1. Always provide a defaultValue when the component may render on the server.
2. Use Chakra’s theme breakpoints directly instead of hard‑coding pixel values to stay in sync with design changes.
3. Wrap components that depend heavily on breakpoint values in React.memo to avoid extra renders.
4. Test the component in both mobile and desktop viewports, and verify that the logged value matches the expected breakpoint.
5. When using SSR frameworks like Next.js, confirm that the initial page load shows the fallback value to avoid hydration mismatches.

By following these guidelines, you can leverage useBreakpointValue to keep your responsive logic declarative, maintainable, and tightly coupled to your design system.