Skip to main content

Class Merging

Configure custom class conflict rules, createCn, useCn, and MoraineProvider cnConfig integration.

View as Markdown

Moraine includes a class merger built on cn and configured for UnoCSS and Tailwind 4. It resolves conflicting utility classes (for example p-2 and p-4, or bg-primary and bg-muted) and adds rules for Moraine’s semantic shadows, z-index, text size, tone, and parametric transform utilities. Class inputs use cn’s ClassValue type. An empty merge returns undefined, which suits DOM bindings.

Merging Classes#

import { cn } from 'moraine'

// Conflicting padding resolves to the last applied class ('p-4'):
const className = cn('p-2 text-sm', 'p-4 text-foreground')
// => "text-sm p-4 text-foreground"

The exported cn always uses the default rules and ignores any MoraineProvider. Call useCn() inside a component to merge with the nearest Provider’s rules.

Keep UnoCSS’s automatic class sorting enabled. Sorting orders tokens within a string, while cn resolves conflicts across the inputs it receives, and later classes win. Put component overrides in a later input or in the appropriate override layer. Avoid placing competing values such as p-2 p-4 in the same string, because sorting can change which one comes last.

Custom Class Conflict Rules#

If your project adds utility classes that conflict with each other (such as custom density or brand utilities), teach the merger about them with createCn or MoraineProvider:

src/lib/app-cn.ts
import { createCn } from 'moraine'
import type { CnConfig } from 'moraine'

export const appCnConfig = {
  extend: {
    classGroups: {
      density: ['density-roomy', 'density-compact'],
    },
  },
} satisfies CnConfig

const appCn = createCn(appCnConfig)

const className = appCn('density-roomy', 'density-compact')
// => "density-compact"

CnConfig is the cn library’s configuration extension, so besides extend it also accepts override, prefix, and cacheSize. createCn applies it on top of the library defaults and Moraine’s rules.

Scoping with MoraineProvider#

Pass your cnConfig to MoraineProvider so that every nested Moraine component and every useCn() call uses your conflict rules:

src/App.tsx
import { Button, MoraineProvider, useCn } from 'moraine'
import { appCnConfig } from './lib/app-cn'

function DensityExample() {
  const scopedCn = useCn()

  return (
    <div class={scopedCn('density-roomy', 'density-compact')}>
      {/* Button uses the nearest Provider's merger */}
      <Button class="density-roomy density-compact">Compact Action</Button>
    </div>
  )
}

export function App() {
  return (
    <MoraineProvider cnConfig={appCnConfig}>
      <DensityExample />
    </MoraineProvider>
  )
}

cnConfig Inheritance#

cnConfig prop Behavior
Omitted or undefined Inherits the parent merger, or uses the default Moraine rules at root.
Configuration object Replaces the parent merger with the Moraine defaults plus this config.
{} Resets to the default Moraine rules, dropping any parent’s extensions.