Breakpoints

Base UI utilitiesCopy Anchor Link

ViraUI builds on Base UI. For RTL context, see Direction. For focus management, portals, and similar built-ins, use Base UI's docs.

How it worksCopy Anchor Link

BreakpointsProvider and useBreakpoints let the React tree branch at named min-width thresholds: swap markup, mount different components, or drive props CSS cannot express alone. Prefer CSS @media or container queries when the same elements can just shift with styles.

These helpers are ViraUI-specific and optional. The required overlay shell from Setup does not include them; add them only when you need that kind of branch.

Wrap a client subtree with BreakpointsProvider, then call useBreakpoints('small') for one flag or useBreakpoints() for the full record. The hook only works under the provider.

Passing breakpoints on the provider replaces the default map entirely; it does not merge. Defaults are em-based names: extra-small (30em), small (48em), medium (60em), large (80em), and extra-large (100em). Confirm the live map in @viraui/react/specs under breakpoints.

Matches come from window.matchMedia on the document that mounts the provider, not from a preview frame’s resize handle.

'use client';

import { Stack, BreakpointsProvider, useBreakpoints } from '@viraui/react';

function ResponsiveNav() {
  // `small` matches at min-width 48em and above
  const largeScreen = useBreakpoints('small');

  return (
    <Stack
      render={<nav aria-label="Primary" />}
      direction={largeScreen ? 'row' : 'column'}
    >
      <a href="/">Home</a>
      <a href="/docs">Docs</a>
      <a href="/pricing">Pricing</a>
    </Stack>
  );
}

export function App({ children }: { children: React.ReactNode }) {
  return (
    <BreakpointsProvider>
      <ResponsiveNav />
      {children}
    </BreakpointsProvider>
  );
}

Custom names replace the defaults entirely. There is no partial merge:

<BreakpointsProvider breakpoints={{ compact: '20em', wide: '50em' }}>
  {children}
</BreakpointsProvider>

Common examplesCopy Anchor Link

Direction flipCopy Anchor Link

A studio nav reads one named flag and flips Stack direction when that min-width matches. The provider must wrap every screen that calls the hook.

Match recordCopy Anchor Link

Call useBreakpoints() with no argument when several names drive the same subtree. You get the full name → boolean record for the provider’s current map. Matched names light as green chips.

Custom mapCopy Anchor Link

The breakpoints prop installs a product map for that provider instance. Named hooks must use those keys only. Sparse overrides do not keep default names like small.

Ask your agentCopy Anchor Link

Paste a need like this when CSS alone cannot express the layout change:

On this page: primary nav stacks vertically on phones and sits in a row on larger screens. The feature grid below is one column by default and three columns from tablet size up. On large screens, make the main CTA bigger and show a secondary text link beside it — hide that link on smaller screens. Prefer CSS for style-only changes; branch the React tree only where layout or markup must change.