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

Breakpoints are managed by the LayoutProvider component. You can override default breakpoints by passing a breakpoints prop to the LayoutProvider.

Breakpoint	Min Width	Typical Device
xs	480px	Mobile portrait
s	768px	Mobile landscape / Tablet portrait
m	1024px	Tablet landscape / Small laptop
l	1440px	Desktop
xl	1920px	Large desktop

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

Default breakpoints (server-rendered): When using the default breakpoint system, ServerFlex/ServerGrid generate CSS classes at build time (e.g., m-padding-l, s-flex-column).
Custom breakpoints (client-rendered): When using custom breakpoints via LayoutProvider, ClientFlex/ClientGrid apply responsive styles client-side using useResponsiveClasses for CSS classes and applyResponsiveStyles for inline styles.
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

To use non-default breakpoints, wrap your app in a LayoutProvider:

Tsx

import { LayoutProvider } from "@once-ui-system/core";

<LayoutProvider
  breakpoints={{ xs: 480, s: 768, m: 1024, l: 1440, xl: 1920 }}
>
  <App />
</LayoutProvider>

With custom breakpoints, responsive styles are applied client-side via JavaScript rather than server-rendered CSS classes.

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)