twin.macro

• Add 'as' prop to types by @klzns in https://github.com/ben-rogerson/twin.macro/pull/846
• Upgrade postcss-selector-parser from 6.0.10 to 6.0.13 by @ben-rogerson in https://github.com/ben-rogerson/twin.macro/pull/845
• Upgrade @babel/template from 7.18.10 to 7.22.15 by @ben-rogerson in https://github.com/ben-rogerson/twin.macro/pull/844

New preset

Not a fan of the virtual dom?
Try Twin's new SolidJS preset 🎉

• StackBlitz example
• Setup information

Read more at #817

More updates

• Styled components v6 support added #818
• Escape selectors containing forward slashes #816
• Allow grabbing values containing a decimal with theme #815

• New: Add support for an esm/.ts tailwind.configs #794 thanks to @albohlabs

Note: Twin will now autoload a tailwind.config.ts config file if found when a tailwind.config.[.js/.cjs] doesn't exist.

// tailwind.config.ts
// generate with: `npx tailwindcss init --ts`

import type { Config } from 'tailwindcss'

export default {
  content: ['*'],
  theme: {
    extend: {},
  },
  plugins: [],
} satisfies Config

// tailwind.config.js
// generate with: `npx tailwindcss init --esm`

/** @type {import('tailwindcss').Config} */
export default {
  content: ['*'],
  theme: {
    extend: {},
  },
  plugins: [],
}

// Classic tailwind.config.js for comparison
// generate with: `npx tailwindcss init`

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['*'],
  theme: {
    extend: {},
  },
  plugins: [],
}

🎉 This version adds support for [email protected] - enjoy!

Read the official tailwind release notes for info on all the new goodies.

Install twin and tailwind latest:

npm i -D twin.macro@latest tailwindcss@latest
pnpm i -D twin.macro@latest tailwindcss@latest
yarn add -D twin.macro@latest tailwindcss@latest

Fixed

• Error: "Could not resolve "tailwindcss/stubs/defaultConfig.stub" https://github.com/ben-rogerson/twin.macro/issues/791

• 🌟 Add @apply support in plugins #770
  Develop tailwindcss plugins quickly using twin-supported classes.
• 🌟 All Next.js examples were updated to make SWC run alongside Twin
• Add twin config types #766
• New Jest + React Testing Library example
• Fix the @screen inability to grab complex theme.screens values #763 - Thanks @minzojian
• Fix pieces.some is not a function error #767

This patch contains a fix for stitches:

• Fixed stitches animation-x classes #758

And mostly fixes for arbitrary variant usage:

• Fixed a variant ordering bug when using multiple variants #759
• Fixed an error when non-media at-rules were used in arbitrary variants, eg: [@page]:m-0 #759
• Fixed comma bug where arbitrary variants aren't visited individually for the auto parent selector #757
• Fixed encoding bug in arbitrary variants when a number is added directly after a comma #757
• Added error message when incorrect arbitrary variant combination containing commas is used #757
• Removed a now unneeded error that notified us to add parent selectors #759

Reminder: Update tailwind to latest also or you'll probably see a pieces.some is not a function error:

# `[email protected]` requires `tailwindcss@>=3.2.0`
npm i twin.macro@latest tailwindcss@latest

Release changes

• 🌟 Added support for all new classes in Tailwind v3.2+
  Use new variants like aria-xxx, data-xxx and min-xxx - check the official tailwindcss release posts for more info
• 🌟 Added full Tailwind support for all plugin functions
  It's only taken three versions and a rewrite to achieve and now full plugin support is here!
• 🌟 Added tailwindcss to peerDependencies
  No more waiting for twin to support new Tailwind features, just update tailwindcss
• Improved style de-caching after adjusting values in tailwind.config.js https://github.com/ben-rogerson/twin.macro/pull/693
• Added additional not- versions of many common variants, eg: not-empty:,:not-focus:,:not-required: ref
• When working in a sub directory within a monorepo, twin will now look upwards for a missing tailwind.config.js
  https://github.com/ben-rogerson/twin.macro/pull/693
• A tailwind config object can now be passed in via config - more at docs/config
• tailwind.config.cjs has been added as a fallback https://github.com/ben-rogerson/twin.macro/commit/9e7a7df14d0e254350af7ec08d9b6e5a5689d4b0
• Added support for the important ! prefix on groups, eg: first:!(block mt-5)
• New twin config option: hasLogColors: false to remove log coloring https://github.com/ben-rogerson/twin.macro/commit/bbaec9d490cabf6b6cfd23b484d3fb10a743621c

Container queries

The new tailwind-container-queries plugin works with twin but there are some browser and version requirements:

• Styled components requires minimum of [email protected]
• Emotion requires minimum of @emotion/[email protected]

Update notes

• Twin config option debugPlugins was removed and rolled into another existing option: debug: true
• Class ordering has been synced with tailwindcss
• container has been aligned with tailwind - no longer has a custom margin value

Short Css deprecated

Twins custom "short css" has been deprecated in favour of Tailwind arbitrary properties:

tw`backgroundColor[red]` // short css (no dash next to the `[`)
tw`[backgroundColor:red]` // Updated to an arbitrary property

Emotion error: Value for 'content' without quotes

In Emotion, using before: or after: variants may trigger a console error like this:

You seem to be using a value for 'content' without quotes, try replacing it with `content: '"var(--tw-content)"'`

Update one or both of the packages below to avoid this error (version is when error was fixed):

• @emotion/[email protected]
• @emotion/[email protected]

Arbitrary variants/properties without parent selectors

In arbitrary variants/properties without parent selectors, Twin now needs to add the parent selector for you in order to create a compatible class to run through tailwindcss.
If twin miscalculates where the parent selector should be added then you'll need to add the parent selector yourself.

Arbitrary variant escaping

Twin now replaces all spaces with underscores in arbitrary variants, so to keep any underscores in the output we can escape them:

// Bad
<div class="[.header__menu]:block">...</div>
// Good
<div class="[.header\_\_menu]:block">...</div>

General value escaping

Previously in many instances, escaping required a double backslash before the character (\\).
Now we'll only need a single backslash:

tw`after:content-['\a0']`

Theme values/import and DEFAULT

When theme is used within an arbitrary value or property and there is a DEFAULT value found, the theme value will now return the default value automatically:

// tailwind.config.js
module.exports = {
  theme: { colors: { black: { DEFAULT: "redish" } } },
}
// Usage
tw`bg-[theme(colors.black)]` // Arbitrary value
tw`[background-color:theme(colors.black)]` // Arbitrary property
// ↓ ↓ ↓ ↓ ↓ ↓
({ "backgroundColor": "redish" }); // < DEFAULT key returned
({ "backgroundColor": "redish" }); // < DEFAULT key returned

The theme import now won't return the DEFAULT option automatically.
We can still select the DEFAULT value by specifying it, eg: themecolors.black.DEFAULT.
This makes it possible to grab whole objects from the config without automatically returning the DEFAULT value:

// tailwind.config.js
module.exports = {
  theme: { colors: { black: { DEFAULT: "redish", another: 'greenish' } } },
}

// Usage
import { theme } from 'twin.macro'
theme`colors.black`
// ↓ ↓ ↓ ↓ ↓ ↓
// Whole object returned
({
  "DEFAULT": "redish",
  "another": "greenish"
});

Daisy UI tailwind plugin

DaisyUI often styles their components based on classNames, eg: .btn.loading { ... }
This means in some situations we have to add classNames to the jsx element to add their modifier styling

Some discussion here and at #760

Vite build issue

If you're noticing build issues after upgrading, try updating your Vite config with the updated build target:

optimizeDeps: {
  esbuildOptions: {
    target: "es2020",
  },
},

Support

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

Thanks

A huge thanks and shout out to all the rc contributors helping with features, fixes and bug testing over the past year - you folks are awesome 👋🙏

@omaemae, @ChrisEbert, @Macksi, @atxiii, @mohammadsiyou, @MatthiasDunker, @lguima, @EduardoBautista, @HaidarEzio, @ajmnz

Full Changelog: https://github.com/ben-rogerson/twin.macro/compare/2.8.2...3.0.0

Install release candidate 5:

npm install twin.macro@rc

• Avoid splitting within arbitrary variants during variant group unwrap 09ddd98
• Avoid incorrect parent selector match within arbitrary variants 798638f
• Fix shortCss check 51384af
• Fix separator suggestion issue 1977aaa
• Add support for tailwindConfig.separator 92e902c
• Fix arbitrary variant/property support ed8d1e2
• Improve jest tests #743

Minor rc release with a few patches:

• Improve arbitrary variant (+ parent selector) support 8de0ce733ec4233ac89ab00361d264987966963e
• Avoid presets overriding the custom twin config 59713cd229cc6bd48a65ab91496e8463bb1e410a
• Avoid incorrectly splitting class within arbitrary values b866af6f8bded90585d843aa88588a6af0c0f97b
• Misc class suggestion/error improvements 0358486fa4f80569db99ab3a1ec5204f6c13c944 a1b438ef7b69cd540290ea8d8db65adf4a8242bd 534742815762762ec16ce67ec177f64a2ca19a0a

Big thanks to everyone who has helped with testing 👍

Minor rc release with a couple small patches:

• Fixed an issue with arbitrary value content classes when coupled with a variant, eg: before:content-['...'] https://github.com/ben-rogerson/twin.macro/commit/a0c5a2d999d0a921c93ab5e535f2e7de2c95496a
• Improved escaping in arbitrary values/properties https://github.com/ben-rogerson/twin.macro/commit/a0c5a2d999d0a921c93ab5e535f2e7de2c95496a

Features and fixes

• 🌟 Update and use new tailwindcss features as soon as they're releasedtailwindcss was moved to peerDependencies meaning you can install new versions of tailwindcss as soon as they're released
• 🌟 Full plugin supportA long time in the making, twin now works with all tailwindcss plugins!
• Disabling core plugins in tailwind.config.js is now supportedMost will use this feature to turn off preflight styles
• Turn off console log coloringIn some frameworks, twin's error logs are added in an error overlay that doesn't support custom log colours - you can fix the display of logs with hasLogColors: false added to your twin config
• Better suggestionsTwin will make better recommendations if you get class wrong
• Better performanceYou'll see much faster conversions, specially in larger codebases

More at https://github.com/ben-rogerson/twin.macro/pull/739

Bugs / Issue discussion →

Install release candidate 3:

npm install twin.macro@rc

Features and fixes

• 🌟 Deprecate short css in favour of arbitrary properties (Breaking change) #705
• ⭐ Add ability to disable preflight styles #707
• Reduced the minimum node version to v16.14.0 54a1db2093dbf0b45d0df8c84354ccdc07d4b5c9
• Fix negative config matching with negative classes #704
• Fix merging with an important ! prefix #702
• Allow non-object values for font-size line-height property #710
• Fix suggestion display on font-sizes 6d351e0edd71066719d8dfc0b3a5428c5854e06c

Bugs / Issue discussion →

Release candidate 2 is ready for testing!

Help test the release with:

npm install twin.macro@rc

Features and fixes

• 🌟 Greatly improved plugin support (daisyui/typography/aspect-ratio/etc) #685 #699
• ⭐ Improve tailwind.config updates by removing excessive caching #693 - thanks @mohammadsiyou
• ⭐ Arbitrary property classes (same as shortcss, different syntax: [color:black]) #700
• ⭐ Improved tailwind.config resolution in monorepos #693 - thanks @mohammadsiyou
• Improved suggestions around opacity #694
• Fixed border-y property #692
• Fixed regression in negative config value matching #691
• Use theme values in short css #690

Bugs / Issue discussion →

Help out by testing the next major version of Twin:

npm install twin.macro@rc

• Bugs / Issue discussion
• Full list of features

Full Changelog: https://github.com/ben-rogerson/twin.macro/compare/2.8.2...3.0.0-rc.1

This patch contains a few changes for those using the styled-components preset.

⚠️ Possible breaking changes

• Remove auto css prop
  The css prop can now be added with babel-plugin-styled-components - Setup info →
• Tweak the styled import preset
  The default import was changed from import "styled-components/macro" to import "styled-components" - More info →

Edit: Try the new rc with the latest changes npm i twin.macro@rc

• Allow font face values added via addBase (#563)

🌟 New: Arbitrary Variants (#546)

The star feature of this release is the addition of a new variant that creates a custom selector for classes.

Usage is easy, just add the selector within square brackets and prefix it on any class (or round-bracketed set):

// Style child elements with the strong tag from the parent container
;<div tw="[strong]:text-red-500">
    <strong>I'm red</strong>
</div>

Before this feature, the styling above would need help from the css prop:

// Style child elements with the strong tag from the parent container
;<div css={{ strong: tw`text-red-500` }}>
    <strong>I'm red</strong>
</div>

There are a wide range of uses for Arbitrary Variants:

// Style the current element based on a theming/scoping className
;<body className="dark-theme">
    <div tw="[.dark-theme &]:(bg-black text-white)">I'm dark theme</div>
</body>

// Add custom height queries
;<div tw="[@media (min-height: 800px)]:hidden">
    I'm shown only on smaller window heights
</div>

// Add custom group selectors
;<button className="group" disabled>
    <span tw="[.group:disabled &]:text-gray-500">I'm gray</span>
</button>

// Use custom at-rules like @supports
;<div tw="[@supports (display: grid)]:grid">I'm grid</div>

// Style the current element based on a dynamic className
;const Component = ({ isLarge }) => <div className={isLarge && 'is-large'} tw="text-base [&.is-large]:text-lg">...</div>

I hope you enjoy using this powerful feature!

🐛 Bugfixes

• Allow dot notation components to be styled with twin (eg: <Menu.Item tw="block">) (#534)
• Add array value types for the screen import (#555) - thanks @mutewinter
• Avoid bg-color classes from trumping bg-opacity-x classes (#552)
• Add helpful feedback when a peer class is used as a tailwind class (#551)
• Convert all numeric values to strings (#540)
• Fix issue with css variables declared in :root using addBase in plugins (#521)
• Enable variants to be used with the container class (#518)
• Restrict debug mode to development (#497) - thanks @u3u

This release brings the same special features we all love from the Tailwind JIT release! (v2.2.0-2.2.7) 🎉🌮
As this is the same feature set as Tailwind, you can read some more information about each feature in the Tailwind release notes.

Larger features

A bunch of new variants

• peer-*: variants for styling sibling elements (PR)
• first-letter: and first-line: pseudo-elements (PR)
• selection: for styling text selections (PR)
• marker: for styling list markers (PR)
• and more: autofill:, in-range:, out-of-range:, first-letter:, first-line:, only:, empty:, selection:, marker:, rtl: and ltr: (PR)

Check the variant config for a full list →

Shorthand color opacity syntax (PR)

Add a slash opacity value to set the opacity on any color classes:

tw`bg-black/50`

// ↓ ↓ ↓ ↓ ↓ ↓

({
  "backgroundColor": "rgba(0, 0, 0, 0.5)"
});

This slash value comes from your opacity setting in your tailwind config.
For custom slash opacity values, use square brackets:

tw`bg-black/[.22]`
tw`bg-black/[--my-opacity-variable]`

Extended arbitrary value support (PR)

The "dash square bracket" syntax adds custom values on just about every dynamic class (like bg-[xxx], not block):

tw`col-start-[73] placeholder-[#aabbcc] object-[50%]`

// ↓ ↓ ↓ ↓ ↓ ↓

({
  "gridColumnStart": "73",
  "::placeholder": {
    "--tw-placeholder-opacity": "1",
    "color": "rgba(170, 187, 204, var(--tw-placeholder-opacity))"
  },
  "objectPosition": "50%"
});

This feature almost replace twin's "short css" feature but short css is still great for more obscure css as you can specify custom properties too:

tw`--my-var[red]`
tw`-webkit-gradient[gradient here]`

Per-side border color utilities (PR)

You can now specify border color and border width on a specific border direction:

// Colors
tw`border-t-gray-50`;
tw`border-b-red-500`;

// ↓ ↓ ↓ ↓ ↓ ↓

({
  "--tw-border-opacity": "1",
  "borderTopColor": "rgba(249, 250, 251, var(--tw-border-opacity))"
});
({
  "--tw-border-opacity": "1",
  "borderBottomColor": "rgba(239, 68, 68, var(--tw-border-opacity))"
});

// Widths
tw`border-t-4`;
tw`border-b-4`;

// ↓ ↓ ↓ ↓ ↓ ↓

({
  "borderTopWidth": "4px"
});
({
  "borderBottomWidth": "4px"
}); 

Smaller features

• before: and after: variants now automatically add content: '' (PR)No more requirement for the content class every time we use pseudo classes
• Simplified transform and filter compositionNow there's no need to add transform or filter to make your actual transform or filter classes work (Possible breaking change - check Adams PR notes)
• Add new transform-cpu classThis class uses translateX and translateY instead of translate3d which is added by transform-gpu
• Background origin utilities (Thanks @theonesean) (PR)Classes for controlling how an element's background is positioned relative to borders, padding, and content - Docs
• Caret color utilities (PR)Specify the color of the carat in textareas/inputs/contenteditables (eg: tw`caret-red-500` )

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! 🍻

• Patched regression with styled-components and the autoCssProp which caused excess imports (#241)

• Fixes release 2.6.0: There was a finger slip on the last release 🤦