Twind.style
  1. Advanced
  2. Aliases

Advanced

Aliases

Aliases allow to define a set of utilities as a single utility.

Aliases are used to create a set of utilities which can be referenced by a single utility. This is useful to create a set of utilities which are used together often.

  1. shortcut — styles are generated as defined by twind — same as if they where used alone
  2. apply — styles are generated in order they are declared

They can be defined inline (within a class attribute or class name string), the rules configuration, or using a helper function. Additionally, they can be named or anonymous.

The generated style of an alias is always a single class and put into the shortcuts layer. This allows other utilities to override the styles of an alias.

Tip

For complex scenarios, it is recommended to use style instead of aliases.

Shortcut Aliases

Shortcut aliases are the simplest type of aliases. They are used to create a shortcut for multiple utilities where the styles are generated as defined by twind — same as if they where used alone.

Inline Shortcuts

html
<!-- anonymous -->
<div class="~(py-2 px-4 font-semibold rounded-lg shadow-md)">
  <!-- ... -->
</div>

<!-- named -->
<div class="Card~(py-2 px-4 font-semibold rounded-lg shadow-md)">
  <!-- ... -->
</div>

Shortcuts are especially useful within component libraries as they allow users of the library to selectively override the styles of a component.

jsx
import { cx } from '@twind/core'

function Card({ className, ...props }) {
  return (
    <div
      className={cx(
        'Card~(py-2 px-4 font-semibold rounded-lg shadow-md)',
        className,
      )}
      {...props}
    />
  )
}

// Standard style
<Card />

// Override style
<Card className="rounded-sm shadow-none" />

shortcut helper

Important

> shortcut does not inject the styles into the document. The returned class name must be used within a class attribute or a class name string.

js
import { shortcut } from '@twind/core'

// anonymous
const card = shortcut('py-2 px-4 font-semibold rounded-lg shadow-md')

// named
const card = shortcut.Card('py-2 px-4 font-semibold rounded-lg shadow-md')

Apply Aliases

Apply aliases are similar to shortcut aliases but styles are generated in order they are declared. This matches the behavior of the @apply directive of Tailwind CSS (Extracting classes with @apply).

Consider the following utilities: py-2 p-4.

  • shortcut — The py-4 utility will override the p-2 utility
  • apply — The p-4 utility will override the py-2 utility
Caution

Almost always you want to use shortcut instead of apply. The only exception is when the implicit order of styles does not match your expectation.

Inline Apply

html
<!-- anonymous -->
<div class="@(py-2 px-4 font-semibold rounded-lg shadow-md)">
  <!-- ... -->
</div>

<!-- named -->
<div class="Card@(py-2 px-4 font-semibold rounded-lg shadow-md)">
  <!-- ... -->
</div>

apply helper

Important

> apply does not inject the styles into the document. The returned class name must be used within a class attribute or a class name string.

js
import { apply } from '@twind/core'

// anonymous
const card = apply('py-2 px-4 font-semibold rounded-lg shadow-md')

// named
const card = apply.Card('py-2 px-4 font-semibold rounded-lg shadow-md')