Flex

Flex is the element the rest of Once UI is made of. It renders a flex container and takes every layout, spacing, size and surface prop in the system, so a page is composed by nesting it rather than by writing CSS. You will rarely write Flex itself. Row and Column are the same component with direction preset, and reading <Column gap="16"> beats reading <Flex direction="column" gap="16">:

Prefer Row and Column

<Column gap="16">   // Flex, direction: column
<Row gap="16">      // Flex, direction: row
<Flex s={{ direction: "column" }}>  // Flex, when the direction changes

Reach for Flex directly when the direction is conditional — a row on desktop that stacks on a phone — since that is the one thing a preset cannot express.

Direction and alignment

horizontal and vertical are named for the axis you see, not for flexbox's main and cross axis, so they mean the same thing whichever way the container runs.

Alignment

<Row gap="8" horizontal="center" vertical="center">
  ...
</Row>

Prop	Type	Default
direction Which way children run. Row and Column preset this.	rowcolumnrow-reversecolumn-reverse	—
horizontal Alignment along the horizontal axis, whatever the direction.	startcenterendbetweenaroundevenstretch	—
vertical Alignment along the vertical axis, whatever the direction.	startcenterendbetweenaroundevenstretch	—
center Shorthand for horizontal and vertical both centred.	boolean	—
wrap Let children flow onto another line instead of shrinking.	boolean	—
flex This element's own grow/shrink value inside its parent.	FlexValue	—

Size

Sizes take a spacing token, a number (read as rem), or any CSS unit. fill and fit are the two you want most: fill the parent, or shrink to the content.

Prop	Type	Default
width Fixed width. A token, a number in rem, or a CSS unit.	numberSpacingTokenCSSUnit	—
height Fixed height. A token, a number in rem, or a CSS unit.	numberSpacingTokenCSSUnit	—
maxWidth Upper bound. The usual way to cap a text column.	numberSpacingTokenCSSUnit	—
minWidth Lower bound.	numberSpacingTokenCSSUnit	—
minHeight Lower bound.	numberSpacingTokenCSSUnit	—
maxHeight Upper bound. Pair with overflowY for a scroll area.	numberSpacingTokenCSSUnit	—
fit Shrink to the content on both axes.	boolean	—
fitWidth Shrink to the content horizontally.	boolean	—
fitHeight Shrink to the content vertically.	boolean	—
fill Fill the parent on both axes.	boolean	—
fillWidth Fill the parent horizontally.	boolean	—
fillHeight Fill the parent vertically.	boolean	—
aspectRatio Hold a ratio as the element resizes, e.g. 16 / 9.	CSSProperties["aspectRatio"]	—

Spacing

Space between siblings is gap on the parent; space inside an element is padding. Prefer both over margin — a layout built from gaps stays correct when a child is added, removed or reordered.

Gap over margin

<Column gap="16" padding="24">    // space between children, space inside
<Column marginBottom="16">        // last resort: space against a sibling

Prop	Type	Default
padding Space inside, all four sides.	SpacingTokennumber	—
paddingLeft	SpacingTokennumber	—
paddingRight	SpacingTokennumber	—
paddingTop	SpacingTokennumber	—
paddingBottom	SpacingTokennumber	—
paddingX Space inside, left and right.	SpacingTokennumber	—
paddingY Space inside, top and bottom.	SpacingTokennumber	—
margin Space outside, all four sides.	SpacingTokennumber	—
marginLeft	SpacingTokennumber	—
marginRight	SpacingTokennumber	—
marginTop	SpacingTokennumber	—
marginBottom	SpacingTokennumber	—
marginX Space outside, left and right.	SpacingTokennumber	—
marginY Space outside, top and bottom.	SpacingTokennumber	—
gap Space between children. "-1" collapses the gap to overlap borders.	SpacingTokennumber-1	—
top Offset, with position set.	SpacingTokennumberCSSUnit	—
right Offset, with position set.	SpacingTokennumberCSSUnit	—
bottom Offset, with position set.	SpacingTokennumberCSSUnit	—
left Offset, with position set.	SpacingTokennumberCSSUnit	—
translateX Shift without affecting layout.	SpacingTokennumberCSSUnit	—
translateY Shift without affecting layout.	SpacingTokennumberCSSUnit	—

Surface

Background, border, radius and shadow are all tokens. A colour is a scheme and a weight (brand-medium, neutral-alpha-weak), never a hex.

Surface

<Flex radius="m" background="surface" border="neutral-alpha-medium" />
<Flex radius="m" background="brand-alpha-weak" border="brand-alpha-medium" />
<Flex radius="l" background="surface" shadow="l" />

Prop	Type	Default
textVariant Set the text style for everything inside in one prop.	TextVariant	—
textSize	xllmsxs	—
textType	labelcodebodyheadingdisplay	—
textWeight	defaultmediumstrongnormal	—
background Surface colour. A token, or surface / page / overlay / transparent.	Colorssurfaceoverlaypagetransparent	—
solid Solid fill, for a control that sits on top of a surface.	Colors	—
borderTop	Colorssurfacetransparentboolean	—
borderRight	Colorssurfacetransparentboolean	—
borderBottom	Colorssurfacetransparentboolean	—
borderLeft	Colorssurfacetransparentboolean	—
borderX	Colorssurfacetransparentboolean	—
borderY	Colorssurfacetransparentboolean	—
border Border colour on all four sides. true uses the neutral default.	Colorssurfacetransparentboolean	—
borderStyle Solid or dashed.	soliddashed	—
borderWidth Border thickness in pixels.	12481248	—
topRadius	xllmsxsnonefull	—
rightRadius	xllmsxsnonefull	—
bottomRadius	xllmsxsnonefull	—
leftRadius	xllmsxsnonefull	—
topLeftRadius	xllmsxsnonefull	—
topRightRadius	xllmsxsnonefull	—
bottomLeftRadius	xllmsxsnonefull	—
bottomRightRadius	xllmsxsnonefull	—
shadow Elevation.	xllmsxs	—
cursor Pointer style. "interactive" is the one to use for anything clickable.	CSSProperties["cursor"]interactiveReactNode	—
radius Corner roundness. Add a nest value to match an inner element.	RadiusSize`${RadiusSize}-${RadiusNest}`	—

Display and behaviour

Prop	Type	Default
as Render a different element — section, article, nav, ul.	ElementType	—
inline Lay out inline rather than as a block.	boolean	—
hide Remove from the layout. Most useful per breakpoint.	boolean	—
pointerEvents "none" lets clicks fall through a decorative layer.	noneallauto	—
position relative is the default, so it never needs writing.	CSSProperties["position"]	—
overflow Clip or scroll the content.	CSSProperties["overflow"]	—
overflowX Clip or scroll horizontally.	CSSProperties["overflowX"]	—
overflowY Clip or scroll vertically. Pair with maxHeight.	CSSProperties["overflowY"]	—
scrollbar "minimal" for a thin scrollbar inside a panel.	defaultminimal	—
transition Named duration and easing for whatever changes.	micro-shortmicro-mediummicro-longmacro-shortmacro-mediummacro-long	—
opacity In steps of 10.	0102030405060708090100	—
zIndex Stacking order.	-1012345678910-1012345678910	—
dark Render only in the dark theme.	boolean	—
light Render only in the light theme.	boolean	—

Text

Text colour is inherited, so it is set on the container rather than on every label inside it.

Prop	Type	Default
onBackground Text colour for content on a background surface.	Colors	—
onSolid Text colour for content on a solid fill.	Colors	—
align Text alignment.	CSSProperties["textAlign"]	—

Responsive

Every prop above can be overridden per breakpoint. Pass an object to xl, l, m, s or xs — they cascade down, so s also applies at xs unless xs says otherwise. This is how layout adapts; media queries are never needed.

Breakpoints

<Row gap="24" s={{ direction: "column", gap: "16" }}>
  <Column fillWidth m={{ hide: true }}>Sidebar</Column>
  <Column fill>Content</Column>
</Row>

Prop	Type	Default
xl Overrides applied at the xl breakpoint and below.	FlexBreakpointProps	—
l Overrides applied at the l breakpoint and below.	FlexBreakpointProps	—
m Overrides applied at the m breakpoint and below.	FlexBreakpointProps	—
s Overrides applied at the s breakpoint and below.	FlexBreakpointProps	—
xs Overrides applied at the xs breakpoint.	FlexBreakpointProps	—

Row and Column — the presets you will use instead
Grid — for two-dimensional layout
Spacing — the token scale behind gap and padding
Color — the scheme and weight behind background and border

Direction and alignment

Size

Spacing

Surface

Display and behaviour

Text

Responsive

Related