twirlwind

Twirlwind

Tailwind v4-first CSS-to-utility-class serializer for JavaScript/TypeScript.

Converts style objects, CSS declaration strings, and CSSStyleDeclaration values into clean Tailwind utility classes. Prefers canonical utilities, falls back to arbitrary values, then arbitrary properties — every CSS property produces valid output.

Install

npm install twirlwind

Quick start

import { styleToClassName } from 'twirlwind'

styleToClassName({
  display: 'flex',
  justifyContent: 'center',
  padding: '16px 8px',
  backgroundColor: 'oklch(62.3% 0.214 259.815)'
})
// → "flex py-4 px-2 justify-center bg-blue-500"

API

styleToTailwind(input, options?)

Full conversion result with metadata.

import { styleToTailwind } from 'twirlwind'

const result = styleToTailwind({ display: 'flex', width: '37px' })

result.className // "flex w-[37px]"
result.classes // ["flex", "w-[37px]"]
result.exact // ConvertedDeclaration[] — exact utility matches
result.arbitrary // ConvertedDeclaration[] — arbitrary value/property fallbacks
result.unmatched // CssDeclaration[] — declarations that couldn't be converted
result.warnings // ConversionWarning[]

styleToClassName(input, options?)

Returns just the class string.

styleToClassName({ padding: '16px', color: 'white' })
// → "p-4 text-white"

styleToClasses(input, options?)

Returns an array of class strings.

styleToClasses({ margin: '8px 16px' })
// → ["my-2", "mx-4"]

cssTextToTailwind(cssText, options?)

Parses a CSS declaration string.

cssTextToTailwind('display: flex; gap: 16px; padding: 8px')
// → { className: "flex p-2 gap-4", ... }

Input formats

// Style object (camelCase or kebab-case)
styleToClassName({ backgroundColor: 'white', 'font-size': '16px' })

// CSS declaration string
styleToClassName('display: flex; padding: 16px')

// CSSStyleDeclaration (browser)
styleToClassName(element.style)

// Iterable of [property, value] pairs
styleToClassName(
  new Map([
    ['display', 'flex'],
    ['padding', '16px']
  ])
)

Features

Color matching

Matches colors across formats to Tailwind's palette — OKLCH (v4), hex (v3), rgb(), keywords, and opacity modifiers.

styleToClassName({ color: '#ef4444' }) // "text-red-500"
styleToClassName({ color: 'rgb(59 130 246)' }) // "text-blue-500"
styleToClassName({ color: 'oklch(62.3% 0.214 259.815)' }) // "text-blue-500"
styleToClassName({ color: 'oklch(62.3% 0.214 259.815 / 50%)' }) // "text-blue-500/50"
styleToClassName({ color: 'inherit' }) // "text-inherit"
styleToClassName({ color: 'currentColor' }) // "text-current"

Shorthand expansion

CSS shorthands decompose into Tailwind longhands.

styleToClassName({ border: '2px solid #ef4444' })
// → "border-2 border-red-500 border-solid"

styleToClassName({ font: 'bold 16px/1.5 sans-serif' })
// → "font-bold text-base leading-normal font-sans"

styleToClassName({ background: 'white center no-repeat' })
// → "bg-white bg-center bg-no-repeat"

styleToClassName({ transition: 'all 200ms ease-in' })
// → "transition-all duration-200 ease-in"

Multi-value transforms and filters

Compound transform and filter declarations decompose into individual utility classes.

styleToClassName({ transform: 'translateX(8px) rotate(45deg)' })
// → "rotate-45 translate-x-2"

styleToClassName({ filter: 'blur(8px) brightness(0.75)' })
// → "blur brightness-75"

Compression

Expanded longhands compress to shorthand utilities when values match.

styleToClassName({ margin: '8px' }) // "m-2" (not "mt-2 mr-2 mb-2 ml-2")
styleToClassName({ inset: '0' }) // "inset-0"
styleToClassName({ padding: '8px 16px' }) // "py-2 px-4"
styleToClassName({ borderRadius: '8px' }) // "rounded-lg"
styleToClassName({ gap: '12px 12px' }) // "gap-3"

Variants

Nested objects map to Tailwind variants — pseudo-classes, media queries, and container queries.

styleToClassName({
  color: 'white',
  ':hover': { color: '#3b82f6' },
  '@media (min-width: 768px)': { display: 'grid' },
  '@media (prefers-color-scheme: dark)': { backgroundColor: 'black' },
  '@container (min-width: 512px)': { display: 'flex' }
})
// → "text-white hover:text-blue-500 md:grid dark:bg-black @lg:flex"

Scroll snap decomposition

styleToClassName({ scrollSnapType: 'x mandatory' })
// → "snap-x snap-mandatory"

Arbitrary fallback

Every CSS property produces valid output. Unknown properties use [property:value] syntax.

styleToClassName({ scrollTimelineName: '--main' })
// → "[scroll-timeline-name:--main]"

styleToClassName({ width: '37px' })
// → "w-[37px]"

Options

styleToTailwind(input, {
  // Allow arbitrary value utilities like w-[37px]
  allowArbitraryValues: true, // default: true

  // Allow arbitrary property fallbacks like [scroll-timeline-name:--x]
  allowArbitraryProperties: true, // default: true

  // Compress matching longhands to shorthands
  compression: 'safe', // "none" | "safe" | "aggressive"

  // Sort output classes
  sort: 'grouped', // "input" | "tailwind" | "grouped"

  // Color matching strategy
  colorMatch: 'exact', // "exact" | "nearest" | "none"

  // Spacing token multiplier mode
  numericMultipliers: 'integer', // "all" | "integer" | "never"

  // Custom theme colors/spacing
  theme: {
    colors: { brand: '#ff6600' },
    spacing: { '18': '4.5rem' }
  }
})

How it works

• Normalize — camelCase → kebab-case, numeric → px, vendor prefixes, !important
• Expand shorthands — margin, border, font, background, transition, overflow, gap, etc.
• Convert — exact utility → value alias → spacing token → color match → arbitrary value → arbitrary property
• Compress — merge matching longhands back to axis/all shorthand utilities
• Sort — deterministic output ordering

License

MIT