Merge Strategy

theme.classNameMergeStrategy controls how schema classes combine with preset classes.

Merge

merge is the default strategy. Preset classes and schema classes are joined.

theme: {
  preset: "default",
  classNameMergeStrategy: "merge",
  classNames: {
    tableWrapper: "shadow-sm"
  }
}

If the default preset sets tableWrapper, the final class name includes both preset classes and shadow-sm.

Override

override uses the schema class for a slot or variant key when the schema provides one.

theme: {
  preset: "default",
  classNameMergeStrategy: "override",
  classNames: {
    tableWrapper: "rounded-none border"
  }
}

If the schema omits a slot, the preset slot remains.

Variants

The same strategy applies to variant groups and keys.

theme: {
  classNameMergeStrategy: "override",
  variants: {
    actionButton: {
      primary: "bg-black text-white"
    }
  }
}

Only the provided actionButton.primary key is overridden. Other variant keys can still come from the preset.

Common mistakes

• Use override only when the custom class is complete enough for that slot.
• merge concatenates through the local cn() helper. It does not remove conflicting Tailwind classes.