Sizing

One size fits all. Well, five. Every size prop runs on one scale that you can retune in one place.

Every control with a size prop takes its height, padding, icon size and the gap between icon and text from one scale, xs to xl. A Button, an Input and a Select of one size line up in a row, and the list a Select or Combobox opens takes its trigger's size, so its items match the trigger.

One size, one line
xs28px
sm32px
md36px
lg40px
xl48px

Scale

One control, drawn at 2×
  • --control-height-md 36px
  • --control-padding-md 12px
  • --control-icon-md 16px
  • --control-gap-md 8px
SizeHeightPaddingIconGap
xs28px8px14px6px
sm32px10px16px8px
md36px12px16px8px
lg40px12px20px10px
xl48px16px20px12px

Each cell is a variable on :root, added by the tokens item: --control-height-md, --control-padding-md, --control-icon-md, --control-gap-md and so on for every size. They're steps of --spacing, so --control-height-md is calc(var(--spacing) * 9), the same as h-9. Button adds icon-xs to icon-xl: squares of the same heights, for an icon alone.

Leave size out and a control is md, unless where it sits calls for less: the Toolbar parts start at sm and ToastAction at xs, so they fit their bar and their toast. InputGroupButton keeps sizes of its own, 24px xs and 32px sm and their icon- squares, to fit inside the group's frame.

Customising

Override a token on :root, and every control of that size follows:

:root {
  --control-height-md: calc(var(--spacing) * 10);
  --control-padding-md: calc(var(--spacing) * 3.5);
}

A token set on an element reaches only the controls inside it. Menus, select lists and other overlays render at the end of <body>, so they only see :root. NavigationMenu's panels are the exception: they open inside the nav, so a token set on the header reaches them.

What reads it

  • Height: Button and everything built on it (Toggle, ToggleGroup, Toolbar, Pagination), Input, InputFloating's outline variant, Select, Combobox, InputNumber, TagsInput (as a minimum), PinInput, InputTime, InputDate, InputGroup and the DatePicker and DateRangePicker fields laid over it, Menu items and the lists of Select, Combobox and Command, Menubar triggers and menus, DrawerMenu rows, Listbox options, Tree rows, Tabs triggers, NavigationMenu triggers and links, ColorPicker's controls, the days, weekday columns and arrows of Calendar and RangeCalendar, FileUpload's icon circle, file icons and grid tiles, and Rating's stars, whose box is the control height and the star two thirds of it.
  • Padding: the text fields (Input, InputFloating, Select, Combobox, InputNumber, TagsInput, InputTime, InputDate, InputGroup's addons and the DatePicker and DateRangePicker fields), Menu items and the lists of Select, Combobox and Command, Menubar triggers and menus, DrawerMenu rows, Listbox options, Tree rows, Tabs triggers, NavigationMenu triggers and links, and FileUpload's drop zone and file list.
  • Icon: Button and everything built on it, the Select trigger, the Combobox chevron and clear button (2px smaller), InputTime, InputDate, InputGroup's addons and the DatePicker and DateRangePicker triggers, Menu items and the lists of Select, Combobox and Command, Menubar triggers and menus, DrawerMenu rows, Listbox options, Tree rows, Tabs triggers, NavigationMenu triggers and links, the arrows of Calendar and RangeCalendar, and FileUpload's icons.
  • Gap: Button, the Select trigger, Menu items and the lists of Select, Combobox and Command, Menubar triggers and menus, Listbox options, Tree rows, Tabs triggers, NavigationMenu triggers and links, the header and grid of Calendar and RangeCalendar, FileUpload's zone and file list, and Rating, whose stars sit half the gap apart.

Button pads wider than a field, from 10px at xs to 32px at xl, so it reads as an action. DrawerMenu adds room for a thumb on top of the tokens; see below.

Table's row heights are its own, 28px at xs to 60px at xl: a row holds a line of text with room around it, not a control.

Component variables

Lists, checkboxes, radios, switches, calendars, rows and a few more don't size each part on its own. Their root turns size into a few variables, and every part inside reads those. An item, its icon and its check mark stay in step, and you get one place to change them. A part reads a variable through a plain utility, so a class of your own on the part still wins.

Menu and MenuSubContent, MenubarContent and MenubarSubContent, the lists of Select and Combobox, Command and DrawerMenu set these on their panel. Items, group labels, separators, check marks and the search field at the top of a Command or Combobox list read them.

VariableWhat it sets
--menu-item-heightAn item's minimum height. With --menu-pad, also the height of the search field.
--menu-item-pxAn item's side padding. Labels and inset items line up on it.
--menu-item-pyThe padding above and below an item's text. It shows once the text wraps.
--menu-item-gapThe space between an item's icon and its text.
--menu-iconThe size of an item's icons and check marks.
--menu-padThe padding around the items, and the space a separator leaves above and below.
--menu-labelThe text size of a group label, with --menu-label-leading its line height.

On Menu, Select, Combobox and Command, height, side padding, gap and icon are the control tokens of the same size:

SizeHeightSide paddingAbove and belowGapIconPad
xs28px8px6px6px14px2px
sm32px10px8px8px16px4px
md36px12px8px8px16px4px
lg40px12px8px10px20px4px
xl48px16px12px12px20px4px

DrawerMenu is tapped, not clicked. It adds room for a thumb to the same tokens, and its gap follows its side padding:

SizeHeightSide paddingAbove and belowGapIconPad
xs36px10px6px10px14px8px
sm40px12px8px12px16px8px
md48px16px12px16px20px8px
lg56px16px12px16px24px8px
xl64px20px16px20px24px8px

Checkbox, Radio and Switch

A 36px checkbox would be absurd, so these keep steps of their own, one variable each:

Size--choice-size--switch-h
xs14px16px
sm16px20px
md18px24px
lg20px28px
xl24px32px

--choice-size is the box of a Checkbox or Radio. Its touch area, its hover halo, the radio's dot and the space before its label are worked out from it.

--switch-h is the height of a Switch's track. The track is 1.625 times as wide (--switch-w), and the thumb, the icon in it, the touch area and the halo scale with it.

A horizontal Field with a description reads both, to set the control level with the first line of its label.

Calendars

Calendar and RangeCalendar set five on their root: --calendar-cell, the size of a day, a weekday column and the arrows (--control-height-*); --calendar-icon, the chevrons in the arrows (--control-icon-*); --calendar-gap, the space in the header and between it and the grid (--control-gap-*); and the text of the heading and of the weekday and week-number cells, --calendar-heading and --calendar-label, each with a -leading twin for its line height. Months side by side sit twice the gap apart.

Bars, rows, empties and steppers

Menubar sets --menubar-h, --menubar-px, --menubar-gap, --menubar-icon and --menubar-radius on the bar from the control tokens, and --menubar-text with --menubar-text-leading for its triggers.

Item sets --item-media, the box of an ItemMedia: the icon variant draws its glyph at half of it, the image variant adds 8px. Empty sets --empty-icon for a bare icon in EmptyMedia, and --empty-header-gap and --empty-content-gap for its two stacks. Stepper sets --stepper-indicator, --stepper-icon, --stepper-gap and --stepper-separator, and --stepper-text for the number in the indicator. Timeline sets --timeline-indicator, --timeline-icon, --timeline-gap, --timeline-separator and --timeline-spacing, the space between records, and --timeline-text for a number in the indicator. FileUpload sets --file-upload-gap, --file-upload-padding, --file-upload-control (the icon circle, a file's icon box and, times 2.5, a grid tile), --file-upload-icon, --file-upload-remove-icon and --file-upload-radius, and, as a control, the text of its title, description and file names: --file-upload-title, --file-upload-description and --file-upload-name, each with a -leading twin. Item's, Empty's, Stepper's and Timeline's titles and descriptions don't follow the size at all: size is the density of the row, and the text keeps its role.

Text fields

PinInput, InputNumber, TagsInput and InputGroup set --control-text and --control-text-leading on their root: the text size of the field inside, from the md breakpoint up (below it, text stays 16px so phones don't zoom in). The classes that set and read them are textControlText and textControlInnerText from Text Control, the frame every text field shares. PinInput also sets --pin-input-slot, the box of one slot, and TagsInput sets --tags-input-line, the height of the line you type in, and --tags-input-delete, a chip's remove button.

Overriding them

For one component, put the variable in a class on the part that sets it: the panel of a list, or the control itself. It wins over the size's own value.

<SelectContent class="[--menu-item-height:2.5rem]">…</SelectContent>
<DrawerMenu class="[--menu-item-gap:--spacing(3)]">…</DrawerMenu>
<Checkbox class="[--choice-size:1.375rem]" />

For every one, write a rule outside any CSS layer, so it beats Tailwind's utilities, and key it on the slot. The panels of Menu, MenuSubContent, MenubarContent, MenubarSubContent, Select, Combobox, Command and DrawerMenu also carry data-size, and so do Checkbox, Radio and Switch, so a rule can change one size only:

[data-slot='menu'][data-size='md'],
[data-slot='menu-sub-content'][data-size='md'],
[data-slot='select-content'][data-size='md'],
[data-slot='combobox-list'][data-size='md'] {
  --menu-item-height: 2.5rem;
}

Setting one on an ancestor does nothing: the panel or control sets its own value, and its parts see that one.

Next

  • Icons: how icons pick up their size.
  • Radius: the corner roles and how nested corners stay concentric.
  • Accessibility: small controls that are still easy to tap.