https://github.com/hoangnhan2ka3/twg
๐ชฅ A utility function for grouping TailwindCSS variants.
https://github.com/hoangnhan2ka3/twg
classnames clsx grouping-variants tailwind tailwind-variants tailwind-variants-grouping tailwindcss tailwindcss-plugin variants-grouping
Last synced: 4 months ago
JSON representation
๐ชฅ A utility function for grouping TailwindCSS variants.
- Host: GitHub
- URL: https://github.com/hoangnhan2ka3/twg
- Owner: hoangnhan2ka3
- License: other
- Created: 2024-08-17T15:50:53.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-02-19T15:55:46.000Z (4 months ago)
- Last Synced: 2026-02-19T16:48:27.840Z (4 months ago)
- Topics: classnames, clsx, grouping-variants, tailwind, tailwind-variants, tailwind-variants-grouping, tailwindcss, tailwindcss-plugin, variants-grouping
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/twg
- Size: 1.91 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: .github/README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
twg
๐ชฅ A utility function for grouping Tailwind CSS variants.
A more elegant way of writing Tailwind classes. Never need to repeating the same variants over and over again ๐คฏ.
---
| ๐ Entry point | ๐ฆ Bundle | ๐ฆ Gzip |
| :-------------- | :-------: | :--------: |
| `twg` | 732 B | **413 B** |
| `twg/transform` | 3676 B | **1497 B** |
---
## ๐๏ธ Features
- โ
Support for normal strings.
- โ
Support for multiple objects parsing.
- โ
Support for nesting multiple objects, arrays, and itself functions.
- โ
Support for (multiple) conditional classes, objects, and arrays.
- โ
Customizable `callee` name and `separator`.
- โ
Compatible with wrappers like [`twMerge`](https://github.com/dcastil/tailwind-merge).
- โ
"Base" support for Tailwind CSS IntelliSense (IDEs extension), as well as [Hover Preview](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss#hover-preview).
- โ
Tree-shaking friendly.
---
## ๐ Support
| Framework | Version |
| :------------ | :------ |
| `tailwindcss` | `3.x` |
> [!NOTE]
> Tailwind CSS `v4` is not supported. Because they removed [`content.transform`](https://v3.tailwindcss.com/docs/content-configuration#transforming-source-files) API.
> Currently, there is no way to intervene before Tailwind scans the classes.
---
## ๐ Table of contents
- [Quick intro](#-quick-intro)
- [Getting started](#-getting-started)
- [More on docs](#-docs)
- [Changelog](#-changelog)
- [Contributing](#-contributing)
- [Credits](#-credits)
---
## ๐จ Quick intro
Example:
```jsx
Hello, World!
```
Output (html):
```jsx
```
> [!TIP]
> Simply open an Object, put the `variant` as key, and classes you want to map to that `variant` as each value.
> See [usage / use cases](../docs/usage.md) for more details.
---
## ๐ Getting started
**1. Install the package**
```bash
pnpm add twg
```
or
```bash
npm install twg
```
**2. Setup**
```js
// tailwind.config.ts
import { type Config } from "tailwindcss"
import { transformer } from "twg/transform"
export default {
content: {
files: [
"./src/app/**/*.{ts,tsx}",
"./src/components/**/*.{ts,tsx}",
"./src/content/**/*.mdx"
], // Move your old `content` to `content.files` like this
transform: {
DEFAULT: transformer() // Put `transformer()` here
}
},
// ...
} satisfies Config
```
- If you need to override default `transformer()` options:
```js
transform: {
DEFAULT: transformer({
// Define options here, eg.:
callee: "cn"
})
}
```
See all [options](../docs/options.md#-default-version) and how to [custom options](../docs/options.md#-custom-options).
**3. Usage**
```jsx
import { twg } from "twg"
```
- If you need to override default `twg()` options, you need to use `createTwg()` function:
```js
import { createTwg } from "twg"
createTwg({ separator: "_" })(...inputs)
//...
```
See [custom `separator`](../docs/options.md#-custom-separator).
For more information, consider reading [custom options](../docs/options.md#-custom-options) โ๏ธ and [best practice](../docs/usage.md#best-practice-with-twmerge) โ๏ธ.
See [how to use](../docs/usage.md) on docs ๐.
---
## ๐ Docs
- [Usage / Use cases](../docs/usage.md) โ๏ธ
- [Usage](../docs/usage.md#-usage) โ๏ธ
- [Basic usage](../docs/usage.md#-basic-usage) โ๏ธ
- [Complex as โ ๏ธ usage](../docs/usage.md#-complex-as-%EF%B8%8F-usage) โ๏ธ
- [Use cases](../docs/usage.md#-use-cases) โ๏ธ
- [Conditionals](../docs/usage.md#-conditionals) โ๏ธ
- [Nesting callee functions](../docs/usage.md#-nesting-callee-functions) โ๏ธ
- [Combination](../docs/usage.md#-combination) โ๏ธ
- [Options](../docs/options.md) โ๏ธ
- [`transformer()` options](../docs/options.md#transformer-options) โ๏ธ
- [`createTwg()` options](../docs/options.md#createtwg-options) โ๏ธ
- [Custom options](../docs/options.md#-custom-options) โ๏ธ
- [Custom `callee`](../docs/options.md#-custom-callee) โ๏ธ
- [Custom `separator`](../docs/options.md#-custom-separator) โ๏ธ
- [Turn on `debug`](../docs/options.md#-turn-on-debug) โ๏ธ
- [API](../docs/api.md) โ๏ธ
- [Deeper explanation](../docs/introduction.md) โ๏ธ
- [What is `twg`?](../docs/introduction.md#-what-is-twg) โ๏ธ
- [Explanation](../docs/introduction.md#%EF%B8%8F-explanation) โ๏ธ
- [Trade-offs](../docs/introduction.md#-trade-offs) โ๏ธ
## ๐ Changelog
For full & latest update changelog, please refer to [CHANGELOG.md](../CHANGELOG.md).
## ๐ Contributing
### Bugs
`twg` now work for me but maybe not for you in some edges. Consider opening an [issue](https://github.com/hoangnhan2ka3/twg/issues) if you have any problem with it that I can fix it ASAP. Or a [pull request](https://github.com/hoangnhan2ka3/twg/pulls) is welcome too.
### Features
If you have any ideas, feel free to open a [feature request](https://github.com/hoangnhan2ka3/twg/issues/new/choose) template or make a [pull request](https://github.com/hoangnhan2ka3/twg/pulls) to share your ideas.
> For **Development** and more information on contributing please read [CONTRIBUTING.md](../CONTRIBUTING.md).
## ๐ชช Credits
### References
- [easy-tailwind](https://github.com/Noriller/easy-tailwind) โ๏ธ
- [clsx](https://github.com/lukeed/clsx) โ๏ธ
- [tailwind-merge](https://github.com/dcastil/tailwind-merge) โ๏ธ
- [`content.transform` API](https://v3.tailwindcss.com/docs/content-configuration#transforming-source-files) โ๏ธ
### Project starts on
- August 15, 2024
### ๐ช Work with me
### Funding
[](https://github.com/sponsors/hoangnhan2ka3)
---