Twind

Quick Reference

Installation

View in Docs

import { tw } from 'https://cdn.skypack.dev/twind' // requires type="module"
// or
import { tw } from 'twind'

The tw function

View in Docs

The tw function is responsible for composing styles and injecting the derived styles into the document.

  • Template Literal (recommended)

    tw`bg-gray-200 ${false && 'rounded'}`

  • Objects

    tw({ 'bg-gray-200': true, rounded: false, underline: isTrue() })

  • Strings

    tw('bg-gray-200', true && 'rounded', 'underline')

  • Arrays

    tw(['bg-gray-200'], ['', 0, false, 'rounded'], [['underline']])

  • Variadic (mixed)

    tw('bg-gray-200', [
  1 && 'rounded',
  { underline: false, 'text-black': null },
  ['text-lg', ['shadow-lg']],
])

Grouping

View in Docs

The Twind compiler provides a terse syntax for grouping related classes together in an intuitive way.

  • Directive Grouping

    tw`border(2 black opacity-50 dashed)`

  • Variant Grouping

    tw`
  bg-red-500 shadow-xs
  sm:(
    bg-red-600
    shadow-md
  )
  md:(bg-red-700 shadow)
  lg:(bg-red-800 shadow-xl)
`
tw`w(1/2 sm:1/3 lg:1/6) p-2`

  • Mixed Groupings

    tw`sm:(border(2 black opacity-50 hover:dashed))`
tw`border(md:(2 black opacity-50 hover:dashed))`
tw`divide(y-2 blue-500 opacity(75 md:50))`
tw`rotate(-3 hover:6 md:(3 hover:-6))` // (Negated value)

  • Self Reference

    tw`ring(& pink-700 offset(4 pink-200))`)
tw`bg-blue-500(hover:& focus:& active:&) rounded-full`

  • Inherited Groups

    tw`
  hover:${css({ '&::after': { content: '🌈' } })}

  hover:${({ tw }) => ({
    sm: tw`underline`,
    lg: 'no-underline line-through',
  })}

  sm:${['rounded']}
`

The Shim

View in Docs

The shim allows you to use Twind syntax directly in a class attribute without the need of the tw function. It is useful for gradual refactoring or quick prototyping.

import 'twind/shim`;

<!DOCTYPE html>
<html lang="en" hidden>
  <head>
    <script type="module" src="https://cdn.skypack.dev/twind/shim"></script>
  </head>
  <body>
    <main class="h-screen bg-purple-400 flex items-center justify-center">
      <h1 class="font-bold text(center 5xl white sm:gray-800 md:pink-700)">This is Twind!</h1>
    </main>
  </body>
</html>

The apply function

View in Docs

The apply function is used to compose styles that can be later be overwritten in a tw call. Useful for component authors.

import { apply, tw } from 'twind';

const btn = apply`bg-gray-200`;

<button class={tw`${btn}`}>bg-gray-200</button>
<button class={tw`${btn} bg-blue-200`}>bg-blue-500</button>

The css function (CSS-in-JS)

View in Docs

The css function allows you to write raw CSS in Twind, with support for pseudo-selectors, global styles, directives, animations, grouping syntax, and more.

// All available exports
import { tw, css, theme, apply, animation, bounce, keyframes } from 'twind/css'

tw(
  css({
    '&::before': { content: '"🙁"' },
    '&::after': { content: '"😊"' },
  }),
)

tw`
  sm:hover:${css({
    '&::before': { content: '"🙁"' },
    '&::after': { content: '"😊"' },
  })}
`

Configuration

View in Docs

The setup function can optionally be used to configure and extend your theme.

import { setup, strict, voidSheet } from 'twind'
import * as colors from 'twind/colors' // Tailwind V2 colors

setup({
  theme: {
    extend: {
      gray: colors.trueGray,
      colors: { hotpink: '#FF00FF' },
      rotate: { 5: '5deg' },
    },
  },
})

// Advanced
setup({
  preflight: false, // do not include base style reset (default: use tailwind preflight)
  mode: strict, // throw errors for invalid rules: "strict", "warn" or "silent"- default is warn
  hash: true, // hash all generated class names (default: false)
  theme: {}, // define custom theme values (default: tailwind theme)
  darkMode: 'class', // use a different dark mode strategy (default: 'media')
  sheet: voidSheet, // use custom sheet (default: cssomSheet in a browser or no-op)
})

Beyond Tailwind

View in Docs

Twind includes several directives, variants, and utilities beyond Tailwind:

  • SYNTAX

    • Custom syntax for grouping directives and variants (see grouping above)

    • Important!

      <p className="text-red-500!">Hi</p>

  • VARIANTS

    • Every variant can be applied to every directive

    • Dark mode is always available

    • Most pseudo-classes can be used as variant or group-* variant

    • siblings:* - General sibling combinator (& ~ *)

      <p>This is not red.</p>
<p class="siblings:text-red-500">Here is a paragraph.</p>
<p>And here is a red paragraph!</p>
<p>And this is a red paragraph!</p>

    • sibling:* - Adjacent sibling combinator (& + *)

      <p>This is not red.</p>
<p class="sibling:text-red-500">Here is a paragraph.</p>
<p>And here is a red paragraph!</p>
<p>This is not red!</p>

    • children:* - Child combinator (& > *)

      <div class="children:(border my-2)">
  <p>
    This paragraph has <em>emphasized text</em> in it.
  </p>
  <p>
    This paragraph has <em>emphasized text</em> in it.
  </p>
</div>

    • Inherited CSS Properties

      • border-collapse
      • border-separate
      • cursor-*
      • font-*
      • invisible
      • leading-*
      • list-*
      • text-*
      • tracking-*
      • visible
      • whitespace-*

  • DIRECTIVES

    • text-underline
    • text-no-underline
    • text-line-through
    • text-uppercase
    • text-lowercase
    • text-capitalize
    • font-italic
    • font-no-italic
    • bg-gradient-to-* is built-in
    • border and divide- Every permutation of t,r,b,l (can't combine x and y)
    • IE11 support for rotate, scale, skew, and translate
    • appearance-* supports all values