TWCSS

A fast minimalist utility-first CSS runtime inspired by Tailwind and Twind.

Motivation

Tailwind is awesome, but it requires a build setup. Twind exists, but the project appears to be dead.

Features

• Zero setup, zero dependencies. One import does it all. It just works.
• Library agnostic. Works with vanilla JavaScript and any modern framework. Works with Shadow DOM too.
• Lightweight and fast. Minified and gzipped, it's less than 11 kB.

Usage

Node, Deno, Bun:

import 'twcss' // Initialises TWCSS automatically on document.

Directly in browser:

<script src="https://cdn.jsdelivr.net/npm/twcss/target/twcss.min.js"></script>

Then, somewhere in the markup:

<div tw="p-4 bg-indigo-800 text-slate-50 rounded-xl">Hello, world!</div>

React example:

function Wrapper ({ children, isRounded }) {
  // Supports array syntax for convenient conditional styling.
  return (
    <div tw={['p-4 bg-indigo-800 text-slate-50', isRounded && 'rounded-xl']}>
      {children}
    </div>
  )
}

If you prefer to use Twind's approach, do:

import { init } from 'twcss/compiler'

const tw = init(document) // Pass document or shadow root.

function Button ({ children }) {
  return <button className="{tw('p-4 rounded-xl')}">{children}</button>
}

Once imported, TWCSS detects DOM changes with a mutation observer and generates styles on the fly via constructable stylesheets. Simple CSS preflight is included.

Note

TWCSS uses the tw attribute to detect changes. All elements with a tw attribute and without a class attribute are hidden by default to prevent any unwanted layout shift or repaint. Once a tw attribute change is detected, all new styles are generated and the class attribute is set accordingly. For this feature to work properly, TWCSS needs to be loaded before the page content is added.

Extensibility

You can define your own utility classes, colors, animations, and media queries. Overriding existing defaults is also possible.

Node, Deno, Bun:

import { init } from 'twcss/compiler'

// Initialises TWCSS explicitly.
init(document, {
  // Keys are class names and values are blobs of CSS.
  classes: {
    // The below will yield:
    // .foo { width: 123px; height: 123px }
    'foo': '{ width: 123px; height: 123px }',
    // The below will yield:
    // .hide-last-child > :last-child { display: none }
    'hide-last-child': '> :last-child { display: none }',
    // You can use custom keyframes here.
    'animate-spin': '{ animate: spin 1s linear infinite }'
  },
  // Colors use OKLCH color space.
  colors: {
    // All color properties will be able to use this custom color, e.g. outline-octarine/50
    'octarine': '0.9 0.4 20'
  },
  // Keyframes defined here can be used in the classes object.
  keyframes: {
    'spin': 'to { transform: rotate(360deg) }'
  },
  // Custom media queries.
  queries: {
    'xl': '@media screen and (min-width: 1234px)'
  },
  // Custom preflight rules.
  preflight: [
    'body { width: 1000px; margin: 0 auto; }'
  ]
})

HTML:

<script>
  twExtend = {
    // Add your extensions here.
  }
</script>
<script src="https://cdn.jsdelivr.net/npm/twcss/target/twcss.min.js"></script>

Warning

Custom queries must not clash with states or pseudo element.

Compatibility

TWCSS aims at compatibility with Tailwind 4. This is not always possible without compromising on performance. For this reason, certain features are not supported. Please see the REFERENCE.md for the complete list.

Currently unsupported Tailwind 4 features:

• Styling based on parent state via group- prefix.
• Styling based on sibling state via peer- prefix.
• Composite text size - text-<size>/<number>. Font size and line height must be set separately.
• Background gradients - bg-linear-, bg-radial-, bg-conic. Use bg-[] instead.
• Composite border radius - rounded-s-, rounded-e-, rounded-t-, rounded-r-, rounded-b-, rounded-l-.
• Border divisions - divide-.
• Hidden outline - outline-hidden. Use outline-transparent to hide the outline instead.
• Shadow colors; shadows are always black.
• Custom shadows - inset-, ring-, inset-ring-. Use bg-[] instead.
• Mask image gradients; use mask-[] instead.

Changes:

• Default media queries for viewports are sm, md and lg. Feel free to extend them.
• Default animations serve the following use cases:
  • expand for showing menus and opening accordions,
  • toast for popping a notification up from the bottom,
  • fade for adding elements to the page in a visually pleasing manner.
• :has() works only with states via has- prefix (e.g. has-checked).
• :not() works only with states via not- prefix (e.g. not-focus).
• Transition property does not set the transition duration. Use duration-* explicitly.
• New: scrollbar-gutter, scrollbar-width and scrollbar-color support.