Responsive
Choose CSS, container queries, markup branches, or typed prop overrides for responsive UI.
Most responsive bugs start with the wrong engine. When only the styles change, CSS can adapt the layout on its own, with no client boundary and no flash of the wrong layout. When the markup or a ViraUI prop has to change, a React branch is the honest tool.
ViraUI keeps components prop-identical across viewports. There are no per-breakpoint props on the components themselves; the patterns below change the stylesheet, the markup, or a typed props bag instead. They all read the same named thresholds, mobile-first.
Choose what changes
| What changes | Reach for |
|---|---|
| Visibility, grid tracks, media, or other style-only shifts on the same tree | CSS @media |
| A component following its own width instead of the viewport | enableContainer on Stack or Surface |
| Different children or a different component tree | useBreakpoints and a conditional branch |
| A few ViraUI props at a breakpoint | useBreakpoints and a typed Partial<Props> spread |
Ask your agent
Make this filter row stack on phones and sit in a single row from tablet size up. Keep the same elements mounted and let the stylesheet handle the change, so the layout is right on first paint.CSS media queries
Write the narrow layout as the base rule, then add the wider layout inside a min-width query. Use the same length as the active breakpoint map, not a second scale.
.secondary {
display: none;
}
@media (min-width: 60em) {
.secondary {
display: block;
}
}Apply the class to content that only earns its space when the viewport is wide enough. The ViraUI tree and its props stay the same, so the first paint is already correct and no provider or client boundary is involved.
<Stack direction="row" columnGap="m">
<Stack className={styles.primary}>…</Stack>
<Stack className={styles.secondary}>…</Stack>
</Stack>CSS is the right home for style-only shifts such as visibility, grid tracks on your own wrapper, media sizing, or decorative detail. Do not reimplement a ViraUI prop in CSS when that prop is the thing that should change with the viewport; use a markup branch or a props bag below.
Container-aware Stack and Surface
Viewport queries answer the browser width, which is the wrong question inside a split pane or a resizable panel. Set enableContainer on the root that should define the space: a Stack publishes a named container called stack, and a Surface publishes one called surface.
<Surface enableContainer radius="l">
<div className={styles.body}>…</div>
</Surface>@container surface (min-width: 48em) {
.body {
grid-template-columns: 8rem 1fr;
}
}Descendants then respond to that root's inline size instead of the viewport, so the same card works in a narrow sidebar and a wide main column. Query the container you opted into (@container stack or @container surface), and enable containment only on the root you need.
Containment has a cost: an inline-size container can change how nested layout behaves, so avoid it inside masonry-like walls unless the container is the point of the component. Use the same thresholds from the shared breakpoint map.
Branch the markup
Some changes are not styleable. A compact list and a two-pane detail view are different trees, not two presentations of the same one. Wrap the smallest client subtree that branches in BreakpointsProvider, then let the named flag choose the tree.
'use client';
import { BreakpointsProvider, useBreakpoints } from '@viraui/react';
function SettingsShell() {
const isWide = useBreakpoints('medium');
return isWide ? <SettingsSplit /> : <SettingsList />;
}
export function SettingsPage() {
return (
<BreakpointsProvider>
<SettingsShell />
</BreakpointsProvider>
);
}Use useBreakpoints('medium') when one named flag drives the branch. Call useBreakpoints() with no argument when the same subtree reads several names; you get the full name-to-boolean record once instead of asking per name.
The hook only works under the provider, and the provider needs a client boundary. Passing breakpoints on the provider replaces the default map entirely, so a custom map changes the names available here. Breakpoints covers the provider API, defaults, and custom maps.
Override props with a typed bag
A prop that changes at a breakpoint is still a prop. Keep the base JSX as the narrow version, put only the wider differences in a typed bag, and spread the bag after the base props.
'use client';
import { Text, useBreakpoints, type TextProps } from '@viraui/react';
const wideHeading: Partial<TextProps> = { size: 'xl', weight: 'bold' };
function PageHeading() {
const bp = useBreakpoints();
return (
<Text size="l" weight="semibold" {...(bp.medium && wideHeading)}>
Settings
</Text>
);
}- Spread the bag after the base props. Reversed, the base values win and the override disappears.
falsein a spread is a no-op, so no ternary is needed.- Keep bags at module scope and type them with the component's exported props type. No per-breakpoint prop such as
lg={…}orat={…}exists on the components. - When several bags apply, spread from narrowest to widest; at a larger viewport, the smaller names match too.
- Read the full record once when the same render needs more than one flag.
This is still a React branch, so the client boundary and provider rules from the section above apply. Use it for props such as type size, weight, density, or alignment; leave layout-only changes to CSS.
One threshold map
CSS and React should agree on where the layout changes. The active map is the breakpoints prop on the nearest provider, or the built-in map when it is unset. Since breakpoints replaces the map entirely, custom names do not keep the defaults.
Copy the exact lengths into @media and @container. Avoid a parallel 768px scale, theme tokens used as widths, or an ad-hoc matchMedia beside the provider. Author the narrow case first and use min-width for the wider one.
Breakpoints has the built-in lengths, the provider setup, and the live hook examples.
Last updated on