Core Concepts
Reference
Lang
-
comments like in CSS:
/* ... */
-
group~{name}-{modifier}
andpeer~{name}-{modifier}
Name can contain any characters except whitespace, parenthesis (
(
and)
), colon (:
), dash (-
), and opening bracket ([
). -
attribute selector as modifier for groups and peers
With named groups/peers:
CSS (strings and objects)
&
: for nested selectors (CSS Nesting Module)label
: for a more readable class names Emotion › Labelstheme(...)
: access theme values using dot notation; can be used in arbitrary values as well (Tailwind CSS › Functions & Directives › theme())@layer ...
: tell Twind which bucket a set of custom styles belong to (Tailwind CSS › Functions & Directives › layer & Cascade Layers (CSS @layer) spec)- The following layer exist in the given order:
defaults
,base
,components
,shortcuts
,utilities
,overrides
- The following layer exist in the given order:
@apply
: inline any existing utility classes (Tailwind CSS › Functions & Directives › apply)@media screen(...)
: create media queries that reference breakpoints by name instead of duplicating their values (Tailwind CSS › Functions & Directives › screen())
API
The following functions are all exports from twind
.
If you are using the script
tag these methods are available via the twind
global object (eg twind.setup
).
If you have used Tailwind or other CSS-in-JS solutions, then most of the API should feel very familiar.
Shim Mode
Observe class attributes to inject styles
install(config, isProduction): Twind
: configures the globaltw
instance, observes all class attributes and inject the styles into the DOM; returns a twind instancesetup(config, sheet?, target?): Twind
: configures the globaltw
instance, observes all class attributes and inject the styles into the DOM; returns a twind instancetw
: the global twind instance updated by eachsetup
call
Library Mode
twind(config)
: create a twind instanceobserve(tw, target?)
: observes all class attributes and injects the styles into the DOM
Twind instance — tw
-
global twind instance:
import { tw } from '@twind/core'
-
tw(className)
: injects a className string into the sheet and return the resulting class names -
tw.config
: access the current config -
tw.theme(section?, key?, defaultValue?)
: access the current themetw.theme()
: returns the whole themetw.theme(section)
: returns the whole sectiontw.theme(dottedKey, defaultValue?)
: returns the current valuetw.theme(section?, key?, defaultValue?)
: returns the theme value
-
tw.target
: the sheet target of this instance (string[]
,HTMLStyleSheet
,CSSStyleSheet
) -
tw.clear()
: clears all CSS rules from the sheet -
tw.destroy()
: remove the sheet from the document
Utilities
-
defineConfig(config)
: define a configuration object forsetup
ortwind
-
tx(...args)
: creates a class name from the given arguments and injects the styles (liketw(cx(...args))
)tx.bind(tw)
: binds thetx
function to a custom twind instance; returns a newtx
function
-
injectGlobal(...args)
: injects the given styles into the base layerinjectGlobal.bind(tw)
: binds theinjectGlobal
function to a custom twind instance; returns a newinjectGlobal
function
-
keyframes(...args)
: lazily injects the keyframes into the sheet and return a unique namekeyframes.Name(...args)
: lazily injects the named keyframes into the sheet and return a unique namekeyframes.bind(tw)
: binds thekeyframes
function to a custom twind instance; returns a newkeyframes
function
-
animation(animation: string | CSSProperties, waypoints: StringLike)
: lazily injects the animation into the sheet and return a unique nameanimation.Name(animation: string | CSSProperties, waypoints: StringLike)
: lazily injects the named animation into the sheet and return a unique name
Helper functions
These generate class names but do not inject styles.
These can be used to generate class names that are then
a) set the class attribute on an element (Shim Mode)
b) used with tw
to inject styles and return a class name (Library Mode)
-
cx(...args)
: creates a class name from the given arguments; no styles injected -
css(...args)
: creates a class name from the given arguments; no styles injected -
style(options)
: creates a stitches like helper; returns astyle
functionstyle(props)
: creates a class name from the given props; no styles injected
Mostly server side
Used to update an html string with styles.
inline(html, tw? | {tw, minfiy}?)
: updates all class attributes in html string and inject there styles into the head as style element; returns the updated html stringextract(html, tw?)
: updates all class attributes from html string; returns the updated html string and the CSSconsume(html, tw?)
: updates all class attributes from html string; returns the updated html string and injects all styles intotw
Sheets
getSheet(useDOMSheet?: boolean, disableResume?: boolean)
: returns aSheet
for the current environment —virtual
on server, eitherdom
orcssom
in browsersvirtual(includeResumeData?: boolean)
: collect styles into an arraycssom(element?: CSSStyleSheet | Element | null | false)
: uses a fast DOM sheet — bad for debuggingdom(element?: Element | null | false)
: uses a slow DOM sheet — great for debuggingstringify(target)
: returns the CSS string of a sheet target
Config
Dark Mode
Auto Dark Colors
If enabled, automatic dark colors are generated for each light color (eg no dark:
variant is present). This feature is opt-in and twind provides a builtin function that works with tailwind color palettes (50
, 100
, 200
, ..., 800
, 900
).
Example css for text-gray-900
:
The auto-generated dark color can be overridden by the usual dark:...
variant: text-gray-900 dark:text-gray-100
.
Rules
based on ideas from UnoCSS
Hash
hash all shortcuts and apply
add namespace/scope to all classes
Browser Support
In general, Twind is designed for and tested on the latest stable versions of Chrome, Firefox, Edge, and Safari. It does not support any version of IE, including IE 11.
For automatic vendor prefixing include the @twind/preset-autoprefix preset.
For more details see Tailwind CSS › Browser Support.
The following JS APIs may need polyfills:
- Array.flatMap
- Edge<79, Firefox<62, Chrome<69, Safari<12, Opera<56
- polyfill
When using style()
within config.rules
:
- Object.fromEntries
- Edge<79, Firefox<63, Chrome<73, Safari<12.2, Opera<60
- polyfill or @ungap/from-entries
- URLSearchParams
- Edge<17, Firefox<44, Chrome<49, Safari<10.3, Opera<36
- polyfill or @ungap/url-search-params