Box & layout
A token-aware container, flex and grid layouts, typography, icons, and small utilities.
Box
Box renders a styled div (changeable via as) with token-aware style shorthands instead of hand-written CSS. Most other Onset components are built on it. Color, spacing, and radius values all resolve through the theme's --m-* CSS custom properties.
| Prop | Type | Default | Description |
|---|---|---|---|
as | ElementType | "div" | Polymorphic element type. |
bg | ColorToken | — | Background color token (e.g. surface-low, bg-deep). |
border | boolean | ColorToken | — | 1px solid border. Pass true for default, or a color token. |
p | SpaceKey | number | — | Uniform padding. |
px | py | SpaceKey | number | — | Horizontal / vertical padding. |
m | mx | my | SpaceKey | number | — | Margin shorthands. |
w | h | number | string | — | Width / height. |
rounded | RadiusKey | — | Border radius token (e.g. sm, md, lg). |
shadow | "none" | "sm" | "md" | "lg" | — | Box shadow from the theme. |
The full list of style props includes display, position, flex, alignItems, justifyContent, gap, overflow, cursor, opacity, and more. Every prop maps directly to a CSS property, but resolves token values for colors, spacing, radii, and shadows.
Flex, Stack, Inline
Three pre-configured flex containers that share the same BoxProps surface. Use them instead of writing display="flex" on a Box every time.
Flex
Flex renders a Box with display: flex. Configure layout with gap, alignItems, justifyContent, wrap, and direction style props.
Stack
Stack is a vertical flex container: flexDirection: column. Accepts all BoxProps.
Inline
Inline is a horizontal flex container: flexDirection: row with alignItems: center by default. Use it for toolbars, action rows, and label-value pairs.
Grid
Grid is a CSS Grid container built on Box. Use gridTemplateColumns (or the shorthand cols), gap, colGap, and rowGap as style props.
Grid does not set alignItems or justifyContent defaults. Set these props explicitly when needed. Use gridTemplateColumns and gridTemplateRows to define tracks.
Text
Text is the single typography component. Every piece of rendered text in Onset should go through Text (or a component built on it) so the type scale, weight, and color stay on the token system.
| Prop | Type | Default | Description |
|---|---|---|---|
as | ElementType | "span" | Polymorphic element type. |
size | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | ... | "md" | Font size from the type scale. |
weight | "regular" | "medium" | "semibold" | "bold" | "regular" | Font weight. |
color | ColorToken | "fg" | Text color token (e.g. fg-dim, fg-faint, bright). |
family | "sans" | "mono" | "sans" | Font family. |
align | CSSProperties["textAlign"] | — | Text alignment. |
truncate | boolean | — | Single-line with ellipsis overflow. |
uppercase | boolean | — | Uppercase transform with wide letter spacing. |
Icon
Icon is a library-agnostic wrapper for Tabler, Lucide-style, or your own SVG icon components. It keeps icon color and size on the token system (color="fg-dim" instead of a hex value).
| Prop | Type | Default | Description |
|---|---|---|---|
icon | IconComponent | — | A third-party or custom SVG icon component. |
size | number | string | 14 | Icon size in pixels. |
color | ColorToken | string | "fg-dim" | Icon color token or CSS color. |
stroke | string | number | 1.9 | Stroke width forwarded to the icon. |
title | string | — | Accessible SVG title forwarded to the icon component. |
Custom components can type their props with the exported IconComponentProps. size, width, height, color, stroke, title, and other SVG attributes are forwarded. Component props such as Button leftIcon already accept any ReactNode, use Icon when token-based size and color defaults are needed.
Replacing Onset’s internal icons
Wrap a tree in IconProvider to replace any glyph used inside Onset components. The registry is partial and typed: omitted glyphs keep their defaults, while nested providers inherit and can override another subset.
| Prop | Type | Default | Description |
|---|---|---|---|
icons | Partial<IconRegistry> | — | Internal glyph overrides keyed by role. |
children | ReactNode | — | The subtree that receives the overrides. |
Registry keys include search, check, x, chevronDown, calendar, bell, and every other built-in glyph. Import IconRegistry for the complete autocompleteable contract. useIcons() returns the resolved registry, and defaultIconRegistry exposes Onset’s defaults for adapters. The defaults are bundled, so consumers do not need to install Tabler unless their own code imports it.
Utilities
Spacer
Spacer is a flex child that grows to fill available space (equivalent to flex: 1). Use it to push siblings apart in an Inline or Flex.
VisuallyHidden
VisuallyHidden renders content that is only visible to screen readers, positioned off-screen via the standard visually-hidden clip pattern. Use it for accessible labels on icon-only buttons, section headings, and landmark descriptions.
<button aria-label="Search">
<Icon icon={IconSearch} />
</button>;
{
/* Better: a visible label everywhere */
}
<button>
<Icon icon={IconSearch} />
<VisuallyHidden>Search</VisuallyHidden>
</button>;Divider
Divider is a 1px border in --m-color-border. By default it renders horizontally at full width. Set orientation="vertical" for a vertical rule, or place it inside a flex container with a set height.
Kbd
Kbd renders a keyboard shortcut hint: a monospaced keycap in a bordered box. Use it inside context menus, tooltips, and documentation.