{"id":15792908,"url":"https://github.com/brandonmcconnell/tailwindcss-multi","last_synced_at":"2025-04-06T10:13:41.257Z","repository":{"id":174305953,"uuid":"650804610","full_name":"brandonmcconnell/tailwindcss-multi","owner":"brandonmcconnell","description":"Variant-grouped utility support for Tailwind CSS","archived":false,"fork":false,"pushed_at":"2024-05-11T19:23:14.000Z","size":872,"stargazers_count":177,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T05:44:15.715Z","etag":null,"topics":["css","grouping","plugin","plugins","tailwind","tailwindcss","utility-classes"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brandonmcconnell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-07T21:04:23.000Z","updated_at":"2025-01-06T14:31:51.000Z","dependencies_parsed_at":"2024-03-22T20:29:45.737Z","dependency_job_id":"bffd860d-0776-4391-ac6e-02c71f46363a","html_url":"https://github.com/brandonmcconnell/tailwindcss-multi","commit_stats":null,"previous_names":["brandonmcconnell/multitool-for-tailwindcss"],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonmcconnell%2Ftailwindcss-multi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonmcconnell%2Ftailwindcss-multi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonmcconnell%2Ftailwindcss-multi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonmcconnell%2Ftailwindcss-multi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brandonmcconnell","download_url":"https://codeload.github.com/brandonmcconnell/tailwindcss-multi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464224,"owners_count":20942970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","grouping","plugin","plugins","tailwind","tailwindcss","utility-classes"],"created_at":"2024-10-04T23:06:51.937Z","updated_at":"2025-04-06T10:13:41.218Z","avatar_url":"https://github.com/brandonmcconnell.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eMulti for Tailwind CSS\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![minified size](https://img.shields.io/bundlephobia/min/tailwindcss-multi)](https://bundlephobia.com/package/tailwindcss-multi)\n[![license](https://img.shields.io/github/license/brandonmcconnell/tailwindcss-multi?label=license)](https://github.com/brandonmcconnell/tailwindcss-multi/blob/main/LICENSE)\n[![version](https://img.shields.io/npm/v/tailwindcss-multi)](https://www.npmjs.com/package/tailwindcss-multi)\n[![twitter](https://img.shields.io/twitter/follow/branmcconnell)](https://twitter.com/branmcconnell)\n\n\u003c/div\u003e\n\n`tailwindcss-multi` is a plugin for Tailwind CSS that introduces the `multi` directive, a utility that allows you to group utility classes together. This simplifies your HTML and improves readability of your Tailwind CSS code.\n\n### Table of Contents\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Nested variants (quoted values)](#nested-variants-quoted-values)\n    - [Quotes](#quotes)\n- [Why use `tailwindcss-multi`](#why-use-tailwindcss-multi)\n- [Quoted values explanation](#quoted-values-explanation)\n- [What's next?](#whats-next)\n\n\u003e [!IMPORTANT]\n\u003e Update to `@latest` to ensure compatibility with newer versions of Tailwind CSS.\n\u003e \n\u003e **Syntax change:** If you use a value inside `multi-[...]` that includes a colon `:`, the value between the brackets must be quoted, due to a breaking change introduced in Tailwind CSS v3.3.6.\n\u003e ```\n\u003e ✅ hover:multi-[bg-red-500;text-white] // no `:`, so quotes are NOT NEEDED\n\u003e\n\u003e ❌ hover:multi-[hover:bg-red-500;text-white] // using `:`, so quotes are NEEDED 🚨\n\u003e ✅ hover:multi-['hover:bg-red-500;text-white']\n\u003e                 ^                           ^\n\u003e ```\n\u003e See the [Quoted values explanation](#quoted-values-explanation) section for more information.\n\n## Installation\n\nYou can install the plugin via npm:\n\n```bash\nnpm install tailwindcss-multi\n```\n\nThen, include it in your `tailwind.config.js`:\n\n```js\nmodule.exports = {\n  plugins: [\n    require('tailwindcss-multi'),\n  ]\n}\n```\n\n## Usage\n\nThe plugin provides a `multi` directive, allowing you to group multiple utility classes:\n\n```html\n\u003cdiv class=\"hover:multi-[bg-red-500;text-white]\"\u003e\n  When hovered, this text is white and the background is red.\n\u003c/div\u003e\n```\n\u003csup\u003e[View this example on Tailwind Play](https://play.tailwindcss.com/En0nuy58kq)\u003c/sup\u003e\n\nThe directive accepts a semicolon-delimited list of utility classes and applies them to the selected element. A key feature of `tailwindcss-multi` is its support for arbitrary values, which are not limited to predefined classes in Tailwind CSS.\n\n### Nested variants (quoted values)\n\nWhen a value includes a colon `:`, the value must be quoted to ensure compatibility with newer versions of Tailwind CSS. This is due to a breaking change introduced in Tailwind CSS v3.3.6 ([explanation](#quoted-values-explanation)).\n\n\u003e [!NOTE]  \n\u003e One exception to this `:` rule is if the colon is used for a CSS property-value pair, like `multi-[[font-family:times]]`. In this case, quotes are not needed, as this is the expected case for using a colon `:`, which is actually what warranted the breaking change in the first place.\n\u003e\n\u003e So this is valid:\n\u003e ```html\n\u003e \u003cdiv class=\"multi-[[font-family:times]]\"\u003e...\u003c/div\u003e\n\u003e ```\n\n#### Quotes\n\nValid quotes include single `'`, double `\"`, and backticks `` ` ``. The choice of quote is up to you, per usage. Quotes chosen must be kept consistent within the same value.\n\n```html\n\u003c!-- ✅ All valid --\u003e\n\u003cdiv class=\"multi-['hover:font-bold']\"\u003e...\u003c/div\u003e\n\u003cdiv class='multi-[\"hover:font-bold\"]'\u003e...\u003c/div\u003e\n\u003cdiv class=\"multi-[`hover:font-bold`]\"\u003e...\u003c/div\u003e\n\n\u003c!-- ❌ Invalid mix of quotes --\u003e\n\u003cdiv class=\"multi-['hover:font-bold\"]\"\u003e...\u003c/div\u003e\n\u003cdiv class=\"multi-[\"hover:font-bold`]\"\u003e...\u003c/div\u003e\n\u003c!-- etc. --\u003e\n```\n\n## Why use `tailwindcss-multi`\n\nIn some cases, you may need to apply several utilities to a long or convoluted variant or even chain of variants, which can start to look like this:\n\n```html\n\u003cdiv class=\"hover:font-bold hover:text-[red] hover:[font-family:times]\"\u003e\n  When hovered, this text will appear bold, red, and in `times` font.\n\u003c/div\u003e\n```\n\u003csup\u003e[View this example on Tailwind Play](https://play.tailwindcss.com/A3EoS45R14)\u003c/sup\u003e\n\nThis can be difficult to read and understand, especially when the number of utilities increases.\n\nBy employing the `multi` directive, you can group related utility classes by variant, providing clearer insights into your code's function. Below is an example that demonstrates the flexibility of the `multi` directive, demonstrating its ability to support not only multiple utilities, but partially and fully arbitrary values:\n\n```html\n\u003cdiv class=\"hover:multi-[font-bold;text-[red];[font-family:times]]\"\u003e\n  When hovered, this text will appear bold, red, and in `times` font.\n\u003c/div\u003e\n```\n\u003csup\u003e[View this example on Tailwind Play](https://play.tailwindcss.com/NLgm3mPUkf)\u003c/sup\u003e\n\nThis is…\n\n✨ GREAT for consolidating utilities under long \u0026 ideally unique variants 👏🏼\n\n😬 NOT great for keeping the compile size small if you use it with commonly used variants 👀\n\n## Quoted values explanation\n\n```html\n⚫️ `:` not present -\u003e quotes OPTIONAL\n✅ \u003cdiv class=\"hover:multi-[font-bold;text-red-500]\"\u003e...\u003c/div\u003e\n\n⚫️ `:` used in property-value pair -\u003e quotes OPTIONAL\n✅ \u003cdiv class=\"hover:multi-[font-bold;[color:red]]\"\u003e...\u003c/div\u003e\n\n⚫️ `:` used in nested variant -\u003e quotes REQUIRED 🚨\n❌ \u003cdiv class=\"hover:multi-[hover:font-bold;text-red-500]\"\u003e...\u003c/div\u003e\n✅ \u003cdiv class=\"hover:multi-['hover:font-bold;text-red-500']\"\u003e...\u003c/div\u003e\n```\n\u003csup\u003e[View a similar example on Tailwind Play](https://play.tailwindcss.com/yuNA3wIvuH)\u003c/sup\u003e\n\nThe release of [Tailwind CSS v3.3.6](https://github.com/tailwindlabs/tailwindcss/releases/tag/v3.3.6) (on Dec 4, 2023) introduced breaking changes that made the original syntax of Multi for Tailwind CSS incompatible with newer versions of Tailwind CSS.\n\nSee [tailwindlabs/tailwindcss#13473](https://github.com/tailwindlabs/tailwindcss/issues/13473) for the discussion that led to this new syntax.\n\nThis change required a slight tweak to the syntax of the `multi` directive. When using a value that includes a colon `:`, instead of using `multi-[...]`, use `multi-['...']` (with a quoted value between the brackets) to pass the grouped utilities together as a string.\n\n\u003e [!NOTE]  \n\u003e One exception to this `:` rule is if the colon is used for a CSS property-value pair, like `multi-[[font-family:times]]`. In this case, quotes are not needed, as this is the expected case for using a colon `:`, which is actually what warranted the breaking change in the first place.\n\u003e\n\u003e So this is valid:\n\u003e ```html\n\u003e \u003cdiv class=\"multi-[[font-family:times]]\"\u003e...\u003c/div\u003e\n\u003e ```\n\nVersions of Tailwind CSS thereafter (v3.3.6+) are now incompatible with versions of the original unquoted syntax for this plugin (pre-v0.2.0) for values that contain a colon `:`. Update to `@latest` to ensure compatibility. This new version syntax is reverse-compatible with versions of Tailwind CSS prior to v3.3.6 as well.\n\nPassing the joined strings together as a string allows the Tailwind CSS parser (again, in Tailwind CSS v3.3.6+) to see the value as a valid CSS value and process it as expected.\n\n## What's next?\n\nI think the next natural step in the evolution of Multi for Tailwind CSS is to refactor the plugin as a vite/postcss plugin, as either a supplementary or alternate version of the current Tailwind plugin.\n\nThis would allow the plugin to…\n* once again use a custom syntax, without ever needing quotes\n* split any joined utilities into separate classes before the Tailwind CSS parser processes them\n\nIf such a plugin could effectively split classes used with the `multi` directive, it would radically reduce the compile size of the CSS output, as the Tailwind CSS parser would only process the classes used within the `multi`, not the `multi` itself.\n\nFor example, consider the following markup:\n\n```html\n\u003cdiv class=\"sm:hover:bg-red-500 sm:hover:text-white\"\u003e...\u003c/div\u003e\n\u003cdiv class=\"sm:hover:multi-[bg-red-500;text-white]\"\u003e...\u003c/div\u003e\n\u003cdiv class=\"sm:hover:multi-[text-white;bg-red-500]\"\u003e...\u003c/div\u003e\n```\n\nThis generates all of these rules:\n```scss\n@media (min-width: 640px) {\n  .sm\\:hover\\:bg-red-500:hover { /* 2 lines */ }\n  .sm\\:hover\\:text-white:hover { /* 2 lines */ }\n  .sm\\:hover\\:multi-\\[bg-red-500\\;text-white\\]:hover { /* 4 lines */ }\n  .sm\\:hover\\:multi-\\[text-white\\;bg-red-500\\]:hover { /* 4 lines */ }\n}\n```\n\nAs a vite plugin, that markup would be split into individual utilities like this:\n\n```html\n\u003cdiv class=\"sm:hover:bg-red-500 sm:hover:text-white\"\u003e...\u003c/div\u003e\n\u003cdiv class=\"sm:hover:bg-red-500 sm:hover:text-white\"\u003e...\u003c/div\u003e\n\u003cdiv class=\"sm:hover:text-white sm:hover:bg-red-500\"\u003e...\u003c/div\u003e\n```\n\nThis post-split example would only generates these rules:\n\n```scss\n@media (min-width: 640px) {\n  .sm\\:hover\\:bg-red-500:hover { /* 2 lines */ }\n  .sm\\:hover\\:text-white:hover { /* 2 lines */ }\n}\n```\n\nThat's down from 22 lines of output CSS to 10 lines of code, and the same minimal output that would be generated without using the `multi` directive at all.\n\nThe strongest argument against using `multi` is output CSS bloat. This is I caution strongly against throughout this README and provide tips for avoiding.\n\nIt's also something [**@adamwathan**](https://github.com/adamwathan), the creator of Tailwind CSS, discussed at length in [this legendary thread](https://x.com/adamwathan/status/1461519820411789314) when he and his team explored the same problem space from a different angle.\n\nNotice the nicer syntax in that linked thread. Something like that _**might**_ be possible with a vite/postcss plugin.\n\nThis…\n```html\n\u003cdiv class=\"hover:multi-['text-black;dark:text-white']\"\u003e...\u003c/div\u003e\n```\n\n…could become something like this:\n```html\n\u003cdiv class=\"hover:(text-black,dark:text-white)\"\u003e...\u003c/div\u003e\n```\n\n---\n\nI hope you find `tailwindcss-multi` a valuable addition to your projects. If you have any issues or suggestions, don't hesitate to open an issue or pull request.\n\nIf you liked this, you might also like my other Tailwind CSS plugins:\n* [tailwindcss-signals](https://github.com/brandonmcconnell/tailwindcss-signals): Apply styles based on parent or ancestor state, a state-driven alterative to groups\n* [tailwindcss-members](https://github.com/brandonmcconnell/tailwindcss-members): Apply styles based on child or descendant state, the inverse of groups\n* [tailwindcss-mixins](https://github.com/brandonmcconnell/tailwindcss-mixins): Construct reusable \u0026 aliased sets of utilities inline\n* [tailwindcss-selector-patterns](https://github.com/brandonmcconnell/tailwindcss-selector-patterns): Dynamic CSS selector patterns\n* [tailwindcss-js](https://github.com/brandonmcconnell/tailwindcss-js): Effortless build-time JS script injection\n* [tailwindcss-directional-shadows](https://github.com/brandonmcconnell/tailwindcss-directional-shadows): Supercharge your shadow utilities with added directional support (includes directional `shadow-border` utilities too ✨)\n* [tailwindcss-default-shades](https://github.com/brandonmcconnell/tailwindcss-default-shades): Default shades for simpler color utility classes\n* [tailwind-lerp-colors](https://github.com/brandonmcconnell/tailwind-lerp-colors): Expand your color horizons and take the fuss out of generating new—or expanding existing—color palettes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrandonmcconnell%2Ftailwindcss-multi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrandonmcconnell%2Ftailwindcss-multi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrandonmcconnell%2Ftailwindcss-multi/lists"}