Theming

Start with a recipe. Choose a color mode and accent. Override only the tokens your design needs. Every option is typed, serializable, and available to agents through the same component contract.

Explore theme and motion together in the Design Playground.

Color rolesCopy Anchor Link

Colors describe a purpose: surface for the trigger, surfaceRaised for the popup, foreground for text, and highlight for the active item. accent and accentForeground are a pair; focusRing and danger remain independent so interaction and destructive actions stay legible.

<DropdownMenu
  items={items}
  variant="solid"
  theme={{ mode: 'light', accent: 'blue' }}
/>

Use neutral, blue, violet, green, amber, or coral. Omitting the accent keeps the recipe's palette. A supplied accent updates the solid trigger and keyboard focus ring; surfaces remain neutral.

Dark modeCopy Anchor Link

Pass theme.mode="dark" as an object property. The dropdown uses a separately defined dark palette, including its portalled and nested menus. It does not change the page theme or read local storage.

<DropdownMenu
  items={items}
  theme={{ mode: isDark ? 'dark' : 'light', accent: 'violet' }}
/>

Your application owns its theme preference. Pass the same mode to each instance through a shared preset; changing it does not reset menu state.

Shape, spacing, and typographyCopy Anchor Link

recipe chooses studio or soft; size chooses sm, md, or lg. These supply defaults for the same token vocabulary. Explicit tokens win, even when their value is zero.

<DropdownMenu
  items={items}
  recipe="soft"
  size="sm"
  theme={{
    tokens: {
      radius: 6,
      popupRadius: 12,
      itemRadius: 4,
      fontFamily: 'Inter, sans-serif',
      fontSize: 13,
      triggerPadding: 14,
      popupPadding: 8,
      itemPaddingY: 7,
      popupMinWidth: 240,
      shadow: 'floating',
    },
  }}
/>

Numeric geometry and font sizes use pixels. Opacity is unitless; font weight is numeric. Fonts are provided by the host application. Popup widths remain clamped to the viewport; if the preferred minimum exceeds the maximum, the maximum wins.

Token referenceCopy Anchor Link

These values are generated from the schema and resolveTheme(). Defaults below are studio / md / light, without an accent override. The Design Playground starts with blue. soft changes its palette, shape, spacing, and elevation; size changes density. Call resolveTheme(theme, recipe, size) to inspect any combination.

Color values accept hex, numeric rgb() / rgba(), hsl() / hsla(), oklch() / oklab(), transparent, currentColor, or a simple var(--token) reference. Use valid CSS color syntax. Define referenced variables on a shared ancestor such as :root, since a portal can leave a locally scoped container. Keep foreground/background contrast when overriding colors.

Shared application defaultsCopy Anchor Link

import { DropdownMenu, type DropdownPreset } from '@uthereal/ui/dropdown-menu'

const appMenu = {
  recipe: 'studio',
  size: 'sm',
  theme: {
    mode: 'light',
    accent: 'blue',
    tokens: { fontFamily: 'Inter, sans-serif', popupRadius: 12 },
  },
} satisfies DropdownPreset

<DropdownMenu
  preset={appMenu}
  items={items}
  theme={{ tokens: { popupRadius: 0 } }}
/>

Resolution order is library defaults → application preset → instance arguments. Nested option objects merge by field, arrays replace, and undefined leaves the inherited value alone. The example keeps the font and accent but uses square popup corners. Resolved design values then follow recipe and size → color mode and accent → explicit tokens.

React CSS escape hatchCopy Anchor Link

The existing tokens prop still accepts CSS custom properties and inline styles, applied to the trigger container and every popup positioner. It wins over typed theme values. Use it for host-only CSS integration; agents use the validated theme object instead.

<DropdownMenu
  items={items}
  tokens={{ '--ui-accent': 'var(--brand)', '--ui-radius': '10px' }}
/>

The legacy --ui-surface shorthand also colors the popup, and --ui-radius derives popup and item radii unless those CSS variables are supplied separately. Prefer typed tokens for new components: their names, limits, and meaning are exported in the agent schema.