Fields and motion
How fields sit on see-through windows, and how components animate.
Flat, outline, and raised
Buttons, button groups, toggles, and tabs share these looks. For buttons, use raised by default, flat in toolbars and in actions that repeat in a list, and outline for a secondary action next to a raised one.
Depth
Light comes from above. Sunken surfaces have a darker top edge: a darker top border in light mode, and a dark inner line in dark mode. Raised surfaces have a dark lip under the bottom edge. Floating surfaces cast a soft shadow.
One surface for every field
Inputs, checkbox and radio boxes, switch and progress tracks, and chips all use the same see-through white fill.
Field states
Enabled fields are lighter than the window. Invalid fields get a red border. Disabled fields get a dashed border and a hatched fill.
Disabled
Small controls fade to 50%. Fields, cards, and outline buttons get a dashed border and diagonal lines. Raised buttons keep their shape and get diagonal lines on the face. Menu items and text triggers turn muted.
Hover, press, and latched
Neutral controls darken by the text color: 6% on hover, 12% while pressed, and 10% when latched on, such as a pressed toggle or an open menu trigger. Press changes are instant. Orange means checked.
Focus
Keyboard focus shows a ring 2px outside the control. Fields show an orange border and glow. A control at the edge of something that clips or scrolls uses a ring inside its edge instead.
Motion
Most motion uses CSS or the Web Animations API. An open Combobox runs one short frame loop while its field grows, and skips it under reduced motion.
Grain
Containers and floating surfaces get a fine noise texture. Fields, tracks, flat controls, and small labels stay smooth.
Glass
Floating controls over images use liquid glass. Dialogs use a blurred frosted surface. When the user reduces transparency, both become solid.
Status colors
Status names resolve to brand colors: info is blue, success is green, warning is yellow, and error is coral. Use soft when many labels show together, and solid for one label that must stand out.
Sizes
Fields and buttons share three heights: sm is 26px, md is 36px, and lg is 44px. Use md by default, sm in toolbars, table rows, and cards, and lg only for a hero. Use one size in a row.
Corner radius
Small controls use 4px corners. Medium and large controls use 6px. Cards and sections use 8px. Chips and pills are fully round.
Long text
One-line labels in controls and navigation cut off with an ellipsis and show the full text on hover. Messages and descriptions wrap instead.
Messages and descriptions wrap, even a long word like supercalifragilisticexpialidocious_event_name.
Usage
These are defaults, not laws. Break one when you have a good reason, or when it makes the design more cohesive or more interesting.
- Fields use a see-through white fill, so they work on every wallpaper. Do not give a field a gray fill, because gray reads as disabled.
- For your own borders and dividers, use the text color at low opacity, such as
rgb(var(--text-primary)/0.16), not a fixed gray. - Use the shared classes in
styles.tsfor every pattern on this page. Do not copy their values. Tailwind only builds class names that appear in full in the source, so share a value through a named class or a theme entry, never by inserting part of a class name. - Draw a raised lip as a hard outer shadow, and reserve the space for it with
edgeSpace, so a parent that clips or scrolls does not cut it off. - Every movement needs a reduced-motion rule, such as
motion-reduce:transition-none. Decorative loops stop. A spinner keeps turning slowly, because it is the only sign that work is in progress. - Every see-through surface needs a solid fallback under
reduce-transparency:. Bars and tracks usebarForcedTrackandbarForcedIndicatorso they stay visible in forced-colors mode.
API
Props that the library adds. Every part also takes all the Base UI props.
Appearance and depth
| Prop | Type | Default | Description |
|---|---|---|---|
| surfaceAppearances | plain | outlined | raised | – | Container looks for menubars, toolbars, tables, and similar. Use raised on the window, plain inside a card, and outlined in a Section. |
| controlSurface, sunkenTopEdge | darker top border | – | Sunken surfaces: fields, checkbox boxes, inset cards, and snippets. |
| roundControlSurface, trackSurface | inset top shadow | – | Radio boxes, switches, and slider and progress tracks. |
| cardLevels | 1 raised, 2 sunken | – | Cards. Level 1 is raised; a card nested inside it becomes level 2 and sinks in. |
| edgeSpace | 'mb-px' | – | Reserves the 1px under a raised lip. Level 1 cards already include it. |
| overlayShadowSm, raisedOverlayShadowMd, overlayShadowLg | soft shadows | – | Floating surfaces: tooltips, popups and toasts, dialogs and drawers. |
States
| Prop | Type | Default | Description |
|---|---|---|---|
| neutralHover, neutralPress, neutralLatched | 6% · 12% · 10% | – | Neutral hover, instant press, and latched tints. flatPressable combines hover and press. |
| disabledControl | 50% fade | – | Disabled checkboxes, radios, switches, and sliders. |
| fieldState, bg-hatch | dashed border + hatch | – | Disabled fields and cards. Use the bg-hatch class with any variant for the diagonal lines. |
| focusRing, insetFocusRing | outline outside · inside | – | Use the inside ring for a control at a clipping or scrolling edge. |
Material, color, and shape
| Prop | Type | Default | Description |
|---|---|---|---|
| grainSurface | 'ui-grain' | – | Noise texture for containers and floating surfaces. |
| liquidGlassSurface, dialogSurface | blur + fallback | – | Glass for floating controls and for dialogs. Both turn solid under reduced transparency. |
| statusColors, resolveColor | status → color | – | Turns info, success, warning, and error into brand colors for badges, notes, and toasts. |
| controlRadius | sm 4px · md 6px · lg 6px | – | Corners for buttons, fields, and button groups. |
| TruncatedText, wrapText | ellipsis · wrap | – | One-line control and navigation labels, and wrapping content text. |