Styling & Themes

Components accept an appearance prop — a JSON configuration object that controls colors, fonts, spacing, and other visual properties.

Prebuilt themes

Three themes are available out of the box:

// Default — pill-shaped inputs, bold borders
<AddressEntry appearance={{ theme: 'default' }} />

// Minimal — square corners, subtle borders, compact
<AddressEntry appearance={{ theme: 'minimal' }} />

// Rounded — large radii, soft shadows, spacious
<AddressEntry appearance={{ theme: 'rounded' }} />

Overriding design tokens

Use variables to override individual tokens on top of a theme:

<AddressEntry
  appearance={{
    theme: 'minimal',
    variables: {
      colorPrimary: '#003366',
      colorPrimaryHover: '#002244',
      fontFamily: '"Inter", sans-serif',
      borderRadius: '12px',
    },
  }}
/>

Available tokens

Colors

Token	Description
`colorPrimary`	Button background, focus ring, active states
`colorPrimaryHover`	Button hover background
`colorPrimaryText`	Text on primary background
`colorBackground`	Component background
`colorText`	Primary text color
`colorTextSecondary`	Placeholders, hints
`colorBorder`	Input border
`colorBorderFocus`	Input border on focus
`colorError`	Error text and borders
`colorFocusRing`	Focus ring shadow (rgba recommended)
`colorErrorFocusRing`	Error focus ring
`colorSuggestionHover`	Dropdown hover background
`colorDivider`	Divider between suggestions

Typography

Token	Description
`fontFamily`	Font stack for all text
`fontSize`	Base font size
`fontSizeSmall`	Labels, hints, errors
`fontWeightMedium`	Button and label weight

Spacing

Token	Description
`spacing`	Standard padding
`spacingTight`	Compact spacing (icon gaps)
`spacingWide`	Section margins, form field margins

Shape

Token	Description
`borderRadius`	Pill-shaped elements (input, buttons)
`borderRadiusInner`	Dropdown, form inputs
`borderWidth`	Input border width

Shadows

Token	Description
`shadowFocus`	Focus ring box-shadow
`shadowDropdown`	Suggestion dropdown shadow

Sizing

Token	Description
`inputMinHeight`	Input wrapper minimum height
`buttonHeight`	Submit button height
`buttonPaddingX`	Button horizontal padding

How it works

The appearance object is resolved into a complete set of design tokens (resolveAppearance()), then translated to CSS custom properties (appearanceToCSSVars()), and applied as inline styles on the component’s root container. The CSS module references these variables with no fallbacks — all visual values come from the theme.

This means you can render multiple instances with different themes on the same page, and each one is independently styled.

Need more control?

If the appearance tokens don’t cover your needs, you can build fully custom components using the client-js-core API directly. See the Custom UI guide.