Common Mistakes

This page collects common theming mistakes that make docs or previews misleading.

Treating theme as a component adapter

Theme presets change classes. They do not install field adapters, renderers, or external component libraries.

Expecting adapter strings to render external UI

Root adapter can influence the default theme preset and adapter metadata. Rendering external UI controls still requires plugin registration and field adapter usage.

Using the wrong variant group

Core action buttons use variants.actionButton.

theme: {
  variants: {
    actionButton: {
      primary: "bg-blue-600 text-white"
    }
  }
}

Expecting color mode on every slot

theme.colorMode adds a class only on the root slot. Other slots depend on CSS selectors such as Tailwind dark:.

Overriding incomplete slots

With classNameMergeStrategy: "override", provided slot classes replace preset slot classes. Use complete classes when overriding.

Styling rows with column visibility

Table column visibleWhen is column-level visibility. Use theme.classNameWhen or classNameResolver for row/cell styling.

Forgetting registry setup

theme.classNameResolver is a string key. The resolver function must be registered at runtime through createRegistry().