Form Elements

This page shows every form component in the design system at once and lets you flip the surrounding surface so you can see how each control adapts.

The library's form elements are surface-aware: they read their resting and hover backgrounds from CSS variables that Box, Row, and Column set based on their bg prop. The mental model is:

• White surface (bg="white") — form elements rest grey and lift to white on hover/focus.
• Light or grey surface (e.g. bg="base.lightBackground", bg="base.background") — form elements rest white. Hover stays white and the affordance comes from a darker border (gray.500) instead of flipping the fill back to grey.

Use the toggle below to switch the page's example background and watch the inputs invert.

#How surface awareness works

Box, Row, and Column look at their bg prop and, when it matches a recognized surface token, set CSS custom properties on themselves that descendant form elements consume. Defaults are seeded on :root so anything outside an explicitly themed surface keeps the existing appearance.

#CSS variables

• --htui-surface — "light" | "dark". An escape hatch for custom styling if you need to react to the surrounding surface yourself.
• --htui-form-surface-bg — resting background for descendant form elements.
• --htui-form-surface-bg-hover — hover/focus/expanded background for descendant form elements.
• --htui-form-surface-border-hover — hover border color for descendant form elements.
• --htui-form-surface-addon-bg / --htui-form-surface-addon-color — bg and text color for form addons (e.g. the slug input prefix).

If bg is a value the resolver doesn't recognise (responsive object syntax, arbitrary hex, applied via sx, etc.), pass an explicit surface="light" or surface="dark" on Box, Row, or Column to opt into the variables manually.

#Recognized tokens

• Light — white, #fff, #ffffff
• Dark — base.lightBackground, base.background, base.backgroundHover, base.backgroundDisabled, chakra-body-bg, gray.50, gray.100, gray.200

Any other bg value falls through to the surrounding surface's theme, so arbitrary CSS colors (or brand colors like bg="primary.base") don't disturb descendant form elements.

Disabled, invalid, and warning states intentionally still use their explicit tokens regardless of surface.

#Size comparison

Compare how form elements look at different sizes (sm, md, lg) on the same surface toggle.