twin.macro

New: globalStyles import

This release adds a new globalStyles import which contains the preflight/reset styles.

Here's how it can be used with styled-components, instead of the existing GlobalStyles import:

import { createGlobalStyle } from 'styled-components'
import tw, { theme, globalStyles } from 'twin.macro'

const globals = {
  body: {
    WebkitTapHighlightColor: theme`colors.purple.500`,
    ...tw`antialiased`,
  },
}

const GlobalStyles = createGlobalStyle(globalStyles, globals) // Use two arguments so a deep merge happens

export default GlobalStyles

• The existing GlobalStyles import is only for use in jsx, so twin requires the new import for css-in-js solutions like with stitches and @emotion/css where the global import needs to be called outside of jsx.
• I'll be updating most of the examples to use this new import as is easier to understand how the base styles get added.

New: Full preset support for the Stitches css-in-js library

The stitches integration now has much better support for twin features!

Once you add the preset ({ preset: "stitches" }), twin will add features like the tw prop, the css prop (without a styled definition required), and global + plugin styles now work like normal.

This integration took quite a lot of work to achieve, but twin is now in a better position for more integrations in the future 💯

Check out the PR for more information →

• PS: Make sure you watch the Stitches introduction video - it's exceptionally good!
• PS#2: I really wanted to call the preset twitches 🤣

Bugfixes

• Allow the theme import to select DEFAULT values automatically #431
• Fix 'bounce' keyframe definition with animation-timing-function

Support

If you’re kicking ass with twin - especially if you’re in a team - then please consider becoming a sponsor.
It will really help out with the continued development of twin - cheers! 🍻

New: Arbitrary values (#447)

Twin now supports the same arbitrary values syntax popularized by Tailwind’s jit ("Just-in-Time") mode.

tw`top-[calc(100vh - 2rem)]`

// ↓ ↓ ↓ ↓ ↓ ↓

;({ top: 'calc(100vh - 2rem)' })

This is a great way to add once-off values that don’t need to be in your tailwind config.

Read more about arbitrary values →

New: Important prefix (#449)

Also from Tailwind JIT, is the bang ! prefix to add important styles:

tw`!block`;

// ↓ ↓ ↓ ↓ ↓ ↓

;({ "display": "block !important" })

Twin will continue to support a bang at the end of the class too - so you've got a couple of options.

See the pr for more info →

New: Screen import (#408)

The screen import creates media queries for custom css that sync with your tailwind config screen values (sm, md, lg, etc).

Usage with the css prop

import tw, { screen, css } from 'twin.macro'

const styles = [
  screen`sm`({ display: 'block', ...tw`inline` }),
]

<div css={styles} />

Usage with styled components

import tw, { styled, screen, css } from 'twin.macro'

const Component = styled.div(() => [
  screen`sm`({ display: 'block', ...tw`inline` }),
])

<Component />

Read more about the screen import →

Bugfixes

• Fix values issues on [divide/space]-[x-/y-]reverse (#359)

• Support the class strategy in @tailwindcss/forms #440
• Fix ordering of @screen values in plugins #433

• Fixed issues around matching classes that have a hyphen in their name #417
• Improved class suggestions around hyphenated classes #417

This release adds all the new classes from Tailwindcss v2.1.0 🎉

New classes

Filter and backdrop-filter utilities (3923) #402

tw`backdrop-invert-0`;
tw`backdrop-invert`;

tw`backdrop-opacity-0`;
tw`backdrop-opacity-5`;
tw`backdrop-opacity-10`;
tw`backdrop-opacity-20`;
tw`backdrop-opacity-25`;
tw`backdrop-opacity-30`;
tw`backdrop-opacity-40`;
tw`backdrop-opacity-50`;
tw`backdrop-opacity-60`;
tw`backdrop-opacity-70`;
tw`backdrop-opacity-75`;
tw`backdrop-opacity-80`;
tw`backdrop-opacity-90`;
tw`backdrop-opacity-95`;
tw`backdrop-opacity-100`;

tw`backdrop-saturate-0`;
tw`backdrop-saturate-50`;
tw`backdrop-saturate-100`;
tw`backdrop-saturate-150`;
tw`backdrop-saturate-200`;

tw`backdrop-sepia-0`;
tw`backdrop-sepia`;

tw`backdrop-grayscale-0`;
tw`backdrop-grayscale`;

tw`-backdrop-hue-rotate-180`;
tw`-backdrop-hue-rotate-90`;
tw`-backdrop-hue-rotate-60`;
tw`-backdrop-hue-rotate-30`;
tw`-backdrop-hue-rotate-15`;
tw`backdrop-hue-rotate-0`;
tw`backdrop-hue-rotate-15`;
tw`backdrop-hue-rotate-30`;
tw`backdrop-hue-rotate-60`;
tw`backdrop-hue-rotate-90`;
tw`backdrop-hue-rotate-180`;

tw`backdrop-contrast-0`;
tw`backdrop-contrast-50`;
tw`backdrop-contrast-75`;
tw`backdrop-contrast-100`;
tw`backdrop-contrast-125`;
tw`backdrop-contrast-150`;
tw`backdrop-contrast-200`;

tw`backdrop-brightness-0`;
tw`backdrop-brightness-50`;
tw`backdrop-brightness-75`;
tw`backdrop-brightness-90`;
tw`backdrop-brightness-95`;
tw`backdrop-brightness-100`;
tw`backdrop-brightness-105`;
tw`backdrop-brightness-110`;
tw`backdrop-brightness-125`;
tw`backdrop-brightness-150`;
tw`backdrop-brightness-200`;

tw`backdrop-blur-0`;
tw`backdrop-blur-sm`;
tw`backdrop-blur`;
tw`backdrop-blur-md`;
tw`backdrop-blur-lg`;
tw`backdrop-blur-xl`;
tw`backdrop-blur-2xl`;
tw`backdrop-blur-3xl`;

tw`saturate-0`;
tw`saturate-50`;
tw`saturate-100`;
tw`saturate-150`;
tw`saturate-200`;

tw`invert-0`;
tw`invert`;

tw`-hue-rotate-180`;
tw`-hue-rotate-90`;
tw`-hue-rotate-60`;
tw`-hue-rotate-30`;
tw`-hue-rotate-15`;
tw`hue-rotate-0`;
tw`hue-rotate-15`;
tw`hue-rotate-30`;
tw`hue-rotate-60`;
tw`hue-rotate-90`;
tw`hue-rotate-180`;

tw`grayscale-0`;
tw`grayscale`;

tw`drop-shadow-sm`;
tw`drop-shadow`;
tw`drop-shadow-md`;
tw`drop-shadow-lg`;
tw`drop-shadow-xl`;
tw`drop-shadow-2xl`;
tw`drop-shadow-none`;

tw`contrast-0`;
tw`contrast-50`;
tw`contrast-75`;
tw`contrast-100`;
tw`contrast-125`;
tw`contrast-150`;
tw`contrast-200`;

tw`brightness-0`;
tw`brightness-50`;
tw`brightness-75`;
tw`brightness-90`;
tw`brightness-95`;
tw`brightness-100`;
tw`brightness-105`;
tw`brightness-110`;
tw`brightness-125`;
tw`brightness-150`;
tw`brightness-200`;

tw`blur-0`;
tw`blur-sm`;
tw`blur`;
tw`blur-md`;
tw`blur-lg`;
tw`blur-xl`;
tw`blur-2xl`;
tw`blur-3xl`;

Blend mode utilities (3920)

tw`mix-blend-normal`;
tw`mix-blend-multiply`;
tw`mix-blend-screen`;
tw`mix-blend-overlay`;
tw`mix-blend-darken`;
tw`mix-blend-lighten`;
tw`mix-blend-color-dodge`;
tw`mix-blend-color-burn`;
tw`mix-blend-hard-light`;
tw`mix-blend-soft-light`;
tw`mix-blend-difference`;
tw`mix-blend-exclusion`;
tw`mix-blend-hue`;
tw`mix-blend-saturation`;
tw`mix-blend-color`;
tw`mix-blend-luminosity`;

tw`bg-blend-normal`;
tw`bg-blend-multiply`;
tw`bg-blend-screen`;
tw`bg-blend-overlay`;
tw`bg-blend-darken`;
tw`bg-blend-lighten`;
tw`bg-blend-color-dodge`;
tw`bg-blend-color-burn`;
tw`bg-blend-hard-light`;
tw`bg-blend-soft-light`;
tw`bg-blend-difference`;
tw`bg-blend-exclusion`;
tw`bg-blend-hue`;
tw`bg-blend-saturation`;
tw`bg-blend-color`;
tw`bg-blend-luminosity`;

Isolation utilities (3914)

tw`isolate`;
tw`isolation-auto`;

Box-decoration-break utilities (3911)

tw`decoration-slice`;
tw`decoration-clone`;

Inline-table and list-item display utilities (3563, 3929)

tw`inline-table`;
tw`list-item`;

Add ring defaults

ringOffsetWidth.DEFAULT and ringOffsetColor.DEFAULT are now added in the reset styles #405

Missing JIT features from this release

These tailwindcss JIT features will be rolled out in coming releases:

Arbitrary value support

There is no current support for custom tailwind class values - but it will be added to twin:

<button tw="bg-[#1da1f1]" /> // support coming soon

For now, use twin's short css feature that allows any css properties to be added:

<div tw="background-color[#1da1f1]" />

Built-in important modifier

Twin already supports a! added at the end of the class.
I'm going to add support for the same syntax tailwind uses (! at the front):

<div tw="font-bold !font-medium" /> // support coming soon

New features

• Added a config option to disable short css with "disableShortCss": true #409
• Added opacityValue to color functions to better support colors added with css variables #403
• Add unrestricted object nesting in tailwind.config.js #403

Bugfixes

• Added autoprefixer as a dependency to avoid yarn v2 warnings #401
• Fixed negative css variable display #411
• Improved class ordering in user plugins #400

That's all for now, cheers!

• Fix css definitions for bg-clip-x values #375
• Push ring-opacity-x to end of class lists to avoid ordering issues #374
• Added the prop styling guide
• Added the styled component guide

• Fix plus character getting stripped out in short css https://github.com/ben-rogerson/twin.macro/issues/369

• Fix ordering for col-span-x to operate with other grid classes #364
• Fix ordering for transform to play nicer with other transformation classes aebf6da061ec49d55628c19c203fabd57d2d0d06
• Fix ordering for transition to play nicer with other transition classes aebf6da061ec49d55628c19c203fabd57d2d0d06
• Add the correct value for grid-flow-col-dense #365

New: babel-plugin-twin companion plugin

babel-plugin-twin gives you the tw and css prop without having to import 'twin.macro' in your files!

Take a look at babel-plugin-twin →

New: Class commenting (#341)

You can now use comments to disable classes:

// Disable classes with a single-line comment
<div tw="block // flex relative" />; // flex + relative will be ignored

// For more control, use a multi-line comment
<div tw="/* block flex */ relative" />; // block + flex will be ignored

⚡ @lightyen has already added support for comments in the twin intellisense vscode plugin

New: 15 additional variants to style with (#342)

// Style input/textarea placeholders
tw`placeholder:text-black`;

// Target screen + print
tw`screen:flex`;
tw`print:flex`;

// Target screen orientation
tw`landscape:flex`;
tw`portrait:flex`;

// Pointer and hover targeting selectors

// https://developer.mozilla.org/en-US/docs/Web/CSS/@media/any-pointer
tw`any-pointer-none:flex`;
tw`any-pointer-fine:flex`;
tw`any-pointer-coarse:flex`;

// https://developer.mozilla.org/en-US/docs/Web/CSS/@media/pointer
tw`pointer-none:flex`;
tw`pointer-fine:flex`;
tw`pointer-coarse:flex`;

// https://developer.mozilla.org/en-US/docs/Web/CSS/@media/any-hover
tw`any-hover-none:flex`;
tw`any-hover:flex`;

// https://developer.mozilla.org/en-US/docs/Web/CSS/@media/hover
tw`can-hover:flex`;
tw`cant-hover:flex`;

See the pr for more info →

New: Plugin parent selectors (#335)

In custom tailwind plugins you can now use everyones favourite parent selector - the "&".
This selector allows you to add styles if there is a class/attribute on a parent.

This example creates a gap-x-1 class that applies a callback when a class it added higher up the tree:

// tailwind.config.js
const plugin = require("tailwindcss/plugin");

const gapFallback = plugin(({ addUtilities }) =>
  addUtilities({
    '.gap-x-1': {
      rowGap: '1em',
      ".no-flex-gap &": {
        marginTop: '-0.5em',
        marginBottom: '-0.5em',
      },
      ".no-flex-gap & > *": {
        marginTop: '0.5em',
        marginBottom: '0.5em',
      },
    },
  })
);

module.exports = { plugins: [gapFallback] };

// App.js
<body className="no-flex-gap">
  <div tw="gap-x-1">
    Element using modern rowGap with a fallback for older browsers
  </div>
</body>

The above example is just a demonstration, ideally we should loop through the existing gap values instead - check out the pr for a production example.

See the pr for more info →

New: Class prefixing (#348)

Twin now supports the prefix feature from tailwindcss.
This feature lets you specify a prefix for all the tailwind classes to avoid clashing with other styling systems.
Add the prefix to your tailwind config like this:

// tailwind.config.js
module.exports = {
  prefix: "twin-"
};

Then use anywhere you can write tailwind classes:

// App.js
<div tw="twin-block" />
<div css={tw`twin-block`} />
<div className="twin-block" /> // with `includeClassNames: true` in your twin config
styled.div(tw`twin-block`)
tw.div`twin-block`

New: Multiline short css values (f912664b249c0e7a0a0c85e6df7fc522cee59099)

Your longer short css values can be specified on multiple lines:

tw`
box-shadow[
  5px 5px blue,
  10px 10px red,
  15px 15px green;
]
`

New: Keep the data-tw prop while in production

You can now tell twin to keep the data-tw prop in production:

// twin config
"twin": {
  "dataTwProp": "all"
}

Bugfixes

• Fixed the theme import matching some incorrect values (#325)
• Fixed the auto css prop not being added under some conditions (#339 b9578780d18a52ef0926d5b060b7c1b6437aa162)
• Fixed a ReferenceError: tw is not defined error (#339 ffc06dc4f13980900a606ff032572699cbccea1c)

Support

Did you know twin is just over a year old and this is the 48th release? 😱
It's been an utter ride this past year and I'm feeling incredibly grateful for all your positive feedback.
If you’re kicking ass with twin - especially if you’re in a team - then please consider becoming a sponsor. It would really help out - cheers! 🍻

• Fix overscroll behavior definitions 34cd332ab81b9d98e84e0e57badcacccbda1f0f9
• Avoid css has already been declared emotion error 6aea3bcc98e4e084e3b67bbeeb6a573d44e0ea20 #313

• Fixed short css bug matching core plugins #322
• User plugins now allow class names with dots in them eg: flex-gap-y-1.5
• Support for more selector types in user plugins
• Beefed up the addUtilities function support
• Fixed pluginDebug display for escaped classes
• Fixed suggestion display for escaped classes + values that contain objects

🔥 You can now use gap classes with full browser support with the gap polyfill plugin →

This patch adds greater support and bugfixes for the css syntax:

• There's no more need for camel-casing the property name, you can now use dash-case which is much nicer:

  tw`max-width[100vw]`
  

• CSS variables can now be set:

  tw`--my-var[100px]`
  

  And used:

  tw`max-width[var(--my-var)]`
  

• Values with square brackets can now be set:

  tw`grid[[stack] 1fr / min-content [stack] 1fr]`
  

• Browser vendor prefixes now work:

  tw`-webkit-line-clamp[3]`
  

More info in the PR →

This PR brings a new feature which allows you to add custom css right next to your other classes.
It avoids the need to switch to the css prop (or styled.div``) in every occasion - which historically has been mildly annoying, especially when you only need to add a single css property.

The short css syntax is: theCssProperty[the css value] (Camel-case the property for now but use dash-case in the next patch)

Usage:

<div tw="maxWidth[calc(100vw - 2em)]" />

const Component = tw.div`maxWidth[calc(100vw - 2em)]`

tw`maxWidth[calc(100vw - 2em)]`

You can also use this short css syntax with variants, both by themselves or within variant groups:

tw`md:maxWidth[calc(100vw - 2em)]`

tw`md:(h-10 mt-3 maxWidth[calc(100vw - 2em)])`

I've also added a new cs prop if you would like to keep this new syntax separate from your tw classes:

<div cs="md:maxWidth[calc(100vw - 2em)]" />

Just like the data-tw prop, you'll see a data-cs prop in development for traceability.

Examples:

// Setting a content property in a pseudo element
tw`before:(content['hey there'] block)`

// Using a css variable
tw`width[--my-width-variable]`

// Setting grid areas
tw`gridArea[1 / 1 / 4 / 2]`

// Setting grid template areas
tw`gridTemplateAreas['"z z z" "a b c" "d e f"']`

// Setting a vendor prefix like line clamping
tw`webkitLineClamp[3]`

This feature should help trim down some of your styling markup and I really hope you enjoy using it!

Check out the PR for more information + video examples →

• Update the goober global import preset to import { createGlobalStyles } from 'goober/global' #302 - Thanks @gerhardsletten

New: Nested bracket groups (#281)

Now rounded brackets can be used as a tool to add groups of common classes:

<div tw="(text-white bg-black) (mt-3 w-10)" />

Adding a bang ! afterwards will !important all the items in the group:

<div tw="(text-white bg-black)!" />

You can also get crazy with nesting if you need to:

<div tw="md:(bg-red-500 hover:((bg-black text-white) (mt-3 w-10)))" />

Cheers to @lightyen for adding this feature 👍

Check PR#281 for more info →

New: Config presets (#287)

Just like tailwind presets, twin can now use other tailwind.config(s) as a default. This is great for packaging up a base tailwind.config.js and installing it into various projects.

// tailwind.config.js
module.exports = {
  presets: [
      require("my-sweet-default-tailwind-config")
  ],
  // ...
};

Check tailwind preset docs for more info →

New: Matchable classes within the className prop (#282)

After activating this feature, you’ll be able to add tailwind classes within the className prop. It works very similarly to the tw prop but doesn’t show suggestions and instead skips over unmatched classes.

<div className="block mt-5 another-class" />

// ↓ ↓ ↓ ↓ ↓ ↓

<div className="another-class" css={{
    "display": "block",
    "marginTop": "1.25rem"
  }} />

Add includeClassNames: true in your twin config to activate this feature.

Cheers to @mxstbr for the feature idea 👍

Check PR#282 for more info →

• Move preflight styles into GlobalStyles to enable SSR base styles in frameworks like Next.js #262 ^
• Allow nested variant groups: sm:(block hover:(bg-black text-white))
• Remove macro from sc import preset to fix error in cra #264 #279
• Retain the node loc from path.node before it is replaced #256

^ Note for styled-components users: Check that the base styles aren't overriding your component styles after the upgrade. Read this issue for more information.

• Fix space-* and divide-* classes not creating the correct CSS variables #252
• Fix suggestions providing incorrect suggestions around default keys #216

• Add support for addBase in plugins - this now gives twin @tailwindcss/forms support 🎉
• Fixed the --tw-shadow base style implementation a35fc29
• Added a link to the error message for group
• Updated to @types/react@17 to match react@17 #246

• Add support for aspect-ratio plugin #240 #243
• Add support for DEFAULT key in container config #239

• Fixed v2 implementation of box shadow
• Remove @types/react from peerDependencies to fix yarn workspace issues