Utilities
The utility classes behind the elements: token colours, radius, breakpoints and sizes, with the usual layout and spacing classes.
On this page
Utilities are single-purpose classes for the one-off look: a margin, a colour, a grid. They come from UnoCSS, through the Wind preset the ui preset builds on, so the names are the familiar ones (flex, gap-4, p-3, text-sm, grid-cols-2, hidden). The preset changes only what ties them to the UI: colours, radius and breakpoints read the tokens, and a surface fill brings its text colour.
Only what you use is built
The build scans the templates it is given and writes a rule for each class it finds, so the stylesheet holds only what the site uses. A class assembled in a template from pieces, like 'bg-' ~ $color, is never found. Write the whole name, or list the full names a template can produce.
Beating an element
The reset, the base and the element CSS sit in a layer before the utilities, and every element rule is written with :where(). A utility on an element therefore beats the element's own rule at the same specificity, with no !important:
{ui card, class: 'max-w-sm' /}
{ui button, title: 'Wide', class: 'w-full' /}
Colours
Every token is a colour. The fill is bg-{name}, text-{name}, border-{name} and the rest of the colour utilities. A pair names the text that sits on its fill, and bg-primary sets text-primary-contrast for you (bg-well sets text-ink). A text-* class on the same element still wins. Because the tokens change with the theme, a utility written with them follows light, dark and any added theme, and there is no dark: variant to write.
Token colours
<div class="flex flex-wrap gap-2">
<div class="rounded-md bg-primary px-3 py-2 text-sm text-primary-contrast">primary</div>
<div class="rounded-md bg-card px-3 py-2 text-sm text-ink">raised</div>
<div class="rounded-md bg-well px-3 py-2 text-sm text-ink">sunken</div>
<div class="rounded-md bg-hover px-3 py-2 text-sm text-ink">hover</div>
<div class="rounded-md px-3 py-2 text-sm text-muted">muted</div>
<div class="rounded-md bg-destructive px-3 py-2 text-sm text-destructive-contrast">destructive</div>
<div class="rounded-md border px-3 py-2 text-sm">border</div>
</div>
The names are canvas, ink, card, primary, secondary, muted, accent, destructive, success, warning and info, each with a -contrast pair, plus border, input and ring. Theming shows them live.
Alpha
A slash sets the opacity of any colour utility. It is the way to get a soft tint from a status colour.
Alpha
<div class="flex flex-wrap gap-2">
<div class="rounded-md bg-primary/10 px-3 py-2 text-sm text-primary">bg-primary/10</div>
<div class="rounded-md bg-success/15 px-3 py-2 text-sm text-success">bg-success/15</div>
<div class="rounded-md bg-warning/15 px-3 py-2 text-sm text-warning">bg-warning/15</div>
<div class="rounded-md bg-info/15 px-3 py-2 text-sm text-info">bg-info/15</div>
<div class="rounded-md bg-destructive/15 px-3 py-2 text-sm text-destructive">bg-destructive/15</div>
</div>
Radius
rounded-lg is --radius, rounded-md is 2px less and rounded-sm is 4px less. Changing --radius in a theme moves all three, and every element that rounds with the token. rounded-full and rounded-none stay fixed.
Radius
<div class="flex flex-wrap gap-2">
<div class="border px-3 py-2 text-sm rounded-sm">rounded-sm</div>
<div class="border px-3 py-2 text-sm rounded-md">rounded-md</div>
<div class="border px-3 py-2 text-sm rounded-lg">rounded-lg</div>
<div class="border px-3 py-2 text-sm rounded-full">rounded-full</div>
</div>
Breakpoints
A prefix applies a utility from that width up: sm:grid-cols-2 is two columns at 640px and wider. One scale serves every prefix, and xxl takes the place of 2xl.
| Prefix | From |
|---|---|
xs: |
480px |
sm: |
640px |
md: |
768px |
lg: |
1024px |
xl: |
1280px |
xxl: |
1536px |
Start with the layout for the smallest screen and add prefixes as the space grows.
Columns by breakpoint
<div class="grid grid-cols-1 gap-2 sm:grid-cols-2 lg:grid-cols-4">
<div class="rounded-md bg-well p-3 text-sm">One column</div>
<div class="rounded-md bg-well p-3 text-sm">Two from sm</div>
<div class="rounded-md bg-well p-3 text-sm">Four from lg</div>
<div class="rounded-md bg-well p-3 text-sm">Resize the window</div>
</div>
Stack and row
Two classes of the ui sheet, not utilities, cover the most common flex layouts. .stack is a column and .row is a row with its items centred. Both take their gap from data-gap, a step of 1, 2, 3, 4, 6 or 8 (0.25rem to 2rem, the same sizes as gap-1 to gap-8). Without it the gap is 0. They work on any tag, so a list can be <ul class="stack" data-gap="2">.
They sit at the same level as an element's own rules, so a utility still beats them: flex-wrap lets a row wrap, items-start aligns it to the top, gap-12 sets a gap off the scale and lg:flex-row turns a stack into a row from 1024px.
Stack and row
<div
class="stack rounded-lg border p-4"
data-gap="4"
>
<div
class="row"
data-gap="2"
>
<span class="font-semibold">Project</span>
{ui badge, title: 'Active' /}
</div>
<span class="text-muted">Updated today</span>
<div
class="row flex-wrap"
data-gap="2"
>
{ui button, title: 'Open' /}
{ui button, title: 'Share', class: 'button-outline' /}
</div>
</div>
Layout and spacing
The rest are the standard utilities. A flex or grid container with a gap lays out its children, and elements nest inside them like any other tag.
Flex and gap
<div class="flex items-center justify-between gap-4 rounded-lg border p-4">
<div class="flex flex-col gap-1">
<span class="font-semibold">Project</span>
<span class="text-sm text-muted">Updated today</span>
</div>
<div class="flex gap-2">
{ui badge, title: 'Active' /}
{ui button, title: 'Open', class: 'button-outline' /}
</div>
</div>
Tags carry no margin of their own, so space between blocks comes from a gap on the container, or from .prose for running text.
Sizing elements
Elements are measured in em, so the text size classes (text-xs, text-sm, text-base, text-lg, text-xl) size them: text-lg on a button makes the box, the padding and the icon larger, and md:text-lg does it from 768px. A modal's width is not text-relative, so it has two classes, modal-sm and modal-lg. The overview covers size, colour and looks.
Prose
.prose is a class of its own, like .stack and .row. Put it on a container of rendered markdown. It spaces and styles only the container's direct children, so a component placed among them keeps its own look:
<div class="prose">
{$html|noescape}
{ui alert, title: 'Heads up' /}
</div>