Responsive Layout

Call useResponsiveLayout inside any client component to find out which screen size the viewport currently falls into. It returns three booleans, and exactly one is true at any time.

Read the flags and render accordingly. Here the label changes with the current breakpoint.

Resize the window to watch the value update in real time.

const { isMobile, isTablet, isDesktop } = useResponsiveLayout();

const label = isMobile
  ? '📱 Mobile'
  : isTablet
    ? '💻 Tablet'
    : '🖥️ Desktop';

return (
  <Box className="flex items-center gap-2">
    <Text>Current screen size:</Text>
    <Text className="font-strong">{label}</Text>
  </Box>
);

When the markup is same but only a prop should change, set that prop with the flags.

const { isDesktop } = useResponsiveLayout();
const size = isDesktop ? 'standard' : 'large';

return (
  <Button size={size} variant="accentPrimary">
    Continue
  </Button>
);

Use ResponsiveLayoutProvider when the default breakpoints don't fit. Place it once, high in your tree (typically wrapping the design system's Root) to apply your breakpoints across the whole app, or lower to scope them to a specific area.

Each value is the inclusive max-width (in px) for that bucket, so { mobile: 599, tablet: 1279 } means ≤ 599 mobile, 600 to 1279 tablet, ≥ 1280 desktop.

A real use case for this is running inside a WebView on a large tablet (wider than 1024px), which would otherwise be treated as Desktop. Setting tablet: 9999 forces every width below it to resolve as Tablet. Apply the same value in your Tailwind screens config so CSS and the hook stay in agreement.

See Responsive Design to learn more.

function Badge() {
  const { isMobile, isTablet } = useResponsiveLayout();
  const label = isMobile ? 'mobile' : isTablet ? 'tablet' : 'desktop';
  return <Text className="font-strong">{label}</Text>;
}

return (
  <ResponsiveLayoutProvider breakpoints={{ mobile: 599, tablet: 1279 }}>
    <Box className="flex items-center gap-2">
      <Text>Breakpoint (mobile ≤ 599, tablet 600 to 1279, desktop ≥ 1280):</Text>
      <Badge />
    </Box>
  </ResponsiveLayoutProvider>
);

useResponsiveLayout is safe to call in server-rendered apps. On the server there is no window.matchMedia, so the hook falls back to a stable default and returns isDesktop: true. The real viewport is resolved on the client after hydration.

// Server render and first client paint:
//   { isMobile: false, isTablet: false, isDesktop: true }
//
// After hydration, on a 375px-wide phone:
//   { isMobile: true,  isTablet: false, isDesktop: false }
const { isMobile, isDesktop } = useResponsiveLayout();

What this means in practice:

• Don't gate critical or SEO-relevant content on the flags. Content that only renders when isMobile is true is absent from the server HTML and the first paint, then appears after hydration. That means a layout shift, and it stays invisible to crawlers.
• Expect a brief desktop-first frame on small viewports before the client corrects it. For purely visual differences, prefer CSS media queries or Tailwind responsive utilities, which render correctly during SSR with no shift.
• No provider is required for SSR. The default is built in. Use ResponsiveLayoutProvider only when you need to change the breakpoint values.