Responsive Breakpoints

Once UI provides a type-safe responsive breakpoint system where each component only exposes the props it actually supports at each breakpoint.

Breakpoint values

The breakpoints are fixed, and each one applies at its width and below. xl is the base state above all of them, not a media query. LayoutProvider reports the current one through useLayout; it no longer takes a breakpoints prop (removed in 2.0, see the migration guide).

Breakpoint	Applies at	Typical Device
xs	≤ 480px	Mobile portrait
s	≤ 768px	Mobile landscape / Tablet portrait
m	≤ 1024px	Tablet landscape / Small laptop
l	≤ 1440px	Desktop
xl	above 1440px	Large desktop (the base)

Breakpoints cascade downward: xl → l → m → s → xs. A value set at xl applies to all smaller breakpoints unless overridden.

Per-component props

Each component defines its own breakpoint type using BreakpointProps<Source, Keys>, a generic that picks specific keys from the component's prop interfaces and makes them optional.

Flex / Row / Column

Supports layout, spacing, sizing, colors, typography, and effects.

Responsive Flex

Item 1

Item 2

<Flex
direction="row"
padding="16"
background="surface"
xl={{ direction: "row", padding: "32" }}
m={{ direction: "column", padding: "16" }}
s={{ direction: "column", padding: "8" }}
>
<Flex flex={1}>Item 1</Flex>
<Flex flex={1}>Item 2</Flex>
</Flex>

Supported breakpoint props:

Category	Props
Layout	direction, horizontal, vertical, center, wrap, flex
Spacing	padding, paddingLeft, paddingRight, paddingTop, paddingBottom, paddingX, paddingY, margin, marginLeft, marginRight, marginTop, marginBottom, marginX, marginY, gap
Position	top, right, bottom, left, position, hide
Sizing	width, height, maxWidth, minWidth, minHeight, maxHeight, fit, fitWidth, fitHeight, fill, fillWidth, fillHeight, aspectRatio
Colors	background, solid, border, borderTop, borderRight, borderBottom, borderLeft, borderX, borderY, borderStyle, borderWidth, radius, shadow, onBackground, onSolid
Typography	align, textVariant, textSize, textWeight, textType
Effects	opacity, zIndex, pointerEvents, transition, scrollbar, dark, light
Display	overflow, overflowX, overflowY
Escape hatch	style

Grid

Supports grid-specific, spacing, sizing, colors, typography, and effects. Does not support direction, horizontal, vertical, center, wrap, flex.

Responsive Grid

Cell 1

Cell 2

Cell 3

<Grid
columns="3"
gap="16"
m={{ columns: 2 }}
s={{ columns: 1 }}
>
<Flex padding="16">Cell 1</Flex>
<Flex padding="16">Cell 2</Flex>
<Flex padding="16">Cell 3</Flex>
</Grid>

Supported breakpoint props:

Category	Props
Grid-specific	columns, rows
Spacing	padding, paddingLeft, paddingRight, paddingTop, paddingBottom, paddingX, paddingY, margin, marginLeft, marginRight, marginTop, marginBottom, marginX, marginY, gap
Position	top, right, bottom, left, position, hide
Sizing	width, height, maxWidth, minWidth, minHeight, maxHeight, fit, fitWidth, fitHeight, fill, fillWidth, fillHeight, aspectRatio
Colors	background, solid, border, borderTop, borderRight, borderBottom, borderLeft, borderX, borderY, borderStyle, borderWidth, radius, shadow, onBackground, onSolid
Typography	align, textVariant, textSize, textWeight, textType
Effects	opacity, zIndex, pointerEvents, transition, scrollbar, dark, light
Display	overflow, overflowX, overflowY
Escape hatch	style

Card / Dialog / Mask

These extend Flex and inherit all Flex breakpoint props.

Responsive Card

Card content

<Card
background="surface"
radius="l"
padding="24"
xl={{ padding: "32" }}
m={{ padding: "16" }}
>
Content
</Card>

How it works

Type system

The generic BreakpointProps<Source, Keys> type picks specific keys from a source interface and makes them optional:

type BreakpointProps<Source, Keys extends keyof Source> = {
  [K in Keys]?: Source[K];
};

Each component defines its allowed props:

// Flex supports everything
type FlexBreakpointProps = BreakpointProps<AllFlexProps,
  | 'direction' | 'horizontal' | 'vertical' | 'center' | 'wrap' | 'flex'
  | 'padding' | 'gap' | 'width' | 'height' | 'background' | 'opacity'
  // ... etc
>;

// Grid excludes layout props
type GridBreakpointProps = BreakpointProps<AllGridProps,
  | 'columns' | 'rows'
  | 'padding' | 'gap' | 'width' | 'height' | 'background' | 'opacity'
  // ... etc (no direction, horizontal, vertical, center, wrap, flex)
>;

Runtime behavior

Values with a class (server-rendered): a breakpoint value that maps to a utility class — a spacing token, a direction, an alignment — renders as that class on the server (e.g. m-padding-l, s-flex-column), so the layout is right in the first paint.
Values without a class (client-rendered): width, height and their min/max siblings, aspectRatio, style, and spacing given as a number (rem) have no class behind them. An element that sets one of these at a breakpoint renders through ClientFlex/ClientGrid, which applies it as an inline style after hydration, for the breakpoint LayoutProvider reports. Prefer tokens where you can.
Cascade order: xl → l → m → s → xs. Larger breakpoints flow down to smaller ones. Setting xl={{ padding: "32" }} applies padding: 32 at all sizes unless a smaller breakpoint overrides it.

Examples

Hide on mobile

Hide on desktop

Visible on mobile only

<Flex
hide
s={{ hide: false }}
>
Visible on mobile only
</Flex>

Direction change

Left content

Right content

<Flex
direction="row"
horizontal="between"
m={{ direction: "column" }}
>
<Flex>Left content</Flex>
<Flex>Right content</Flex>
</Flex>

Custom breakpoints

Breakpoints are not configurable since 2.0: the utility classes carry the widths inside their @media queries, and a prebuilt stylesheet cannot follow a width an app picks at runtime. If you need a different width for one layout, write a media query in a CSS module for it.

TypeScript API

Exported types for extending the breakpoint system:

import {
  BreakpointProps,
  FlexBreakpointProps,
  GridBreakpointProps,
  TextBreakpointProps,
  ButtonBreakpointProps,
  InputBreakpointProps,
} from "@once-ui-system/core";

// Create custom breakpoint type for your component
type MyComponentBreakpointProps = BreakpointProps<
  MyComponentProps,
  'padding' | 'background' | 'opacity'
>;

Available breakpoint types

Type	Use Case
BreakpointProps<Source, Keys>	Generic: pick any keys from any source
FlexBreakpointProps	Flex, Row, Column, Card, Dialog, Mask, etc.
GridBreakpointProps	Grid, LogoCloud
TextBreakpointProps	Text (if breakpoints added)
ButtonBreakpointProps	Button (if breakpoints added)
InputBreakpointProps	Input (if breakpoints added)