W↓
All docs
🔑
Sign Up/Sign In
www.tailwind-variants.org/docs/
Public Link
Apr 10, 2025, 4:14:19 AM - complete - 24.8 kB
Created by:
****ad@vlad.studio
Starting URLs:
https://www.tailwind-variants.org/docs/
## Page: https://www.tailwind-variants.org/docs/  **Tailwind Variants** a first-class variant API library for TailwindCSS (opens in a new tab). ## Key features #### Variants Since Stitches (opens in a new tab) introduced variants, we became big fans of them, they are a great way to create a consistent design system, so we created **Tailwind Variants** to bring them to TailwindCSS. To learn more about variants, check the variants page. #### Split components into multiple slots You can style multiple components at once using the `slots` property. To learn more about slots and how to use them, check out the Slots page. #### Overrides **Tailwind Variants** provides a `class` / `className` prop for overriding classes on any component. To learn more the overrides, check out this page. #### Components composition **Tailwind Variants** allows you to compose components using the `extend` parameter. It automatically merges the `classes`, `slots`, `variants`, `defaultVariants` and `compoundVariants` of the extended component. To learn more about **Components composition**, check out this page. #### Developer experience **Tailwind Variants** is built with developer experience in mind, it provides a great autocomplete experience thanks to the fully-typed API, so when using TypeScript, `slots`, `values`, and `breakpoints` will be auto-completed for you. #### Automatic conflict resolution **Tailwind Variants** implements **tailwind-merge** (opens in a new tab) under the hood, so it will efficiently merge your classes, so you don't have to worry about TailwindCSS class conflicts. #### Framework agnostic **Tailwind Variants** is a utility library that works with any framework. It's not tied to React. #### Tailwindcss v4 Support **Tailwind Variants** `v1.x` now supports `Tailwindcss v4`. You can check more details in the upgrade guide. ## Community We're excited to see the community adopt HeroUI, raise issues, and provide feedback. Whether it's a feature request, bug report, or a project to showcase, please get involved! * Discord (opens in a new tab) * Twitter (opens in a new tab) * GitHub Discussions (opens in a new tab) * GitHub (opens in a new tab) ## Credits **Tailwind Variants** is heavily inspired by Stitches (opens in a new tab) and CVA (opens in a new tab). Special thanks to Tianen Pang (opens in a new tab) for helping with the API design and library creation. Special thanks to Junior Garcia (opens in a new tab) for building the library and the documentation. Special thanks to Mark Skelton (opens in a new tab) for mantaining the library and the documentation. Special thanks to Joe Bell (opens in a new tab) for creating CVA (opens in a new tab) it served as a great inspiration for this library. Getting Started --- ## Page: https://www.tailwind-variants.org/docs/introduction  **Tailwind Variants** a first-class variant API library for TailwindCSS (opens in a new tab). ## Key features #### Variants Since Stitches (opens in a new tab) introduced variants, we became big fans of them, they are a great way to create a consistent design system, so we created **Tailwind Variants** to bring them to TailwindCSS. To learn more about variants, check the variants page. #### Split components into multiple slots You can style multiple components at once using the `slots` property. To learn more about slots and how to use them, check out the Slots page. #### Overrides **Tailwind Variants** provides a `class` / `className` prop for overriding classes on any component. To learn more the overrides, check out this page. #### Components composition **Tailwind Variants** allows you to compose components using the `extend` parameter. It automatically merges the `classes`, `slots`, `variants`, `defaultVariants` and `compoundVariants` of the extended component. To learn more about **Components composition**, check out this page. #### Developer experience **Tailwind Variants** is built with developer experience in mind, it provides a great autocomplete experience thanks to the fully-typed API, so when using TypeScript, `slots`, `values`, and `breakpoints` will be auto-completed for you. #### Automatic conflict resolution **Tailwind Variants** implements **tailwind-merge** (opens in a new tab) under the hood, so it will efficiently merge your classes, so you don't have to worry about TailwindCSS class conflicts. #### Framework agnostic **Tailwind Variants** is a utility library that works with any framework. It's not tied to React. #### Tailwindcss v4 Support **Tailwind Variants** `v1.x` now supports `Tailwindcss v4`. You can check more details in the upgrade guide. ## Community We're excited to see the community adopt HeroUI, raise issues, and provide feedback. Whether it's a feature request, bug report, or a project to showcase, please get involved! * Discord (opens in a new tab) * Twitter (opens in a new tab) * GitHub Discussions (opens in a new tab) * GitHub (opens in a new tab) ## Credits **Tailwind Variants** is heavily inspired by Stitches (opens in a new tab) and CVA (opens in a new tab). Special thanks to Tianen Pang (opens in a new tab) for helping with the API design and library creation. Special thanks to Junior Garcia (opens in a new tab) for building the library and the documentation. Special thanks to Mark Skelton (opens in a new tab) for mantaining the library and the documentation. Special thanks to Joe Bell (opens in a new tab) for creating CVA (opens in a new tab) it served as a great inspiration for this library. Getting Started --- ## Page: https://www.tailwind-variants.org/docs/getting-started **Tailwind Variants** combines the power of TailwindCSS with a first-class variant API. ## Setup TailwindCSS **Tailwind Variants** requires you to have TailwindCSS installed in your project. If you haven't installed TailwindCSS yet, you can follow the TailwindCSS installation guide (opens in a new tab). ## Installation To use **Tailwind Variants** in your project, you can install it as a dependency: ## Usage ## IntelliSense setup (optional) To enable autocompletion for **Tailwind Variants** you can follow the instructions below. ## Prettier plugin setup (optional) If you are using prettier-plugin-tailwindcss (opens in a new tab) to sort your class names, you can add `tv` to the list of functions that should be sorted. ## Contributing PR's on **Tailwind Variants** are always welcome, please see our contribution guidelines (opens in a new tab) to learn how you can contribute to this project. IntroductionTailwindcss v4 --- ## Page: https://www.tailwind-variants.org/docs/tailwind-v4 TailwindCSS v4 is now available! You can use all the new features and improvements from `Tailwindcss v4` in your projects. Upgrade `tailwind-variants` to `v1.x` to use it. ### Migration Steps To upgrade your project to `v1.x`, you can run the upgrade script. ### Breaking changes * The `responsiveVariants` option has been removed. * `withTv` has been removed. > ❕ Note: `Tailwindcss v4` no longer supports the `config.content.transform` so we remove the `responsiveVariants` feature > > If you want to use `responsiveVariants`, you need to add it manually to your classname. > > e.g. `className="sm:text-sm md:text-base lg:text-lg"` more info here (opens in a new tab). Getting StartedComparison --- ## Page: https://www.tailwind-variants.org/docs/comparison Here's a comparison of Tailwind Variants with other libraries that provide similar functionality. Note: ✅ = supported, ❌ = not supported ### Why Tailwind Variants? A common question that we get is "Why you created **Tailwind Variants**? Why not use **CVA**?", and the fact is that we tried to use CVA (opens in a new tab) in HeroUI (opens in a new tab) to migrate from Stitches to TailwindCSS, but we found it challenging to create a design system solely using CVA. Then we realized that some of the features we needed were not planned to be implemented in CVA as the creator has stated here (opens in a new tab), so we decided to create Tailwind Variants to fill the gap. Our goal is not to compete with CVA, but to provide an alternative that meets our needs to migrate HeroUI (opens in a new tab) to TailwindCSS as smoothly as possible. That being said, big shoutout to Joe Bell (opens in a new tab) and contributors (opens in a new tab) you guys rock! 🤘 - we **recommend** to use CVA if don't need any of the **Tailwind Variants** features listed above. Tailwindcss v4Variants --- ## Page: https://www.tailwind-variants.org/docs/variants Variants allows you to create multiple versions of the same component. ### Adding variants You can add variants by using the `variants` key. There's no limit to how many variants you can add. ### Multiple variants You can add multiple variants to a single component. ### Boolean variants You can also add boolean variants to a component. This is useful when you want to add a state variant e.g. `disabled`. ### Compound variants Sometimes you might want to add a variant that depends on another variant. For example, you might want to add a `color` variant that depends on the `disabled` variant. This is possible by using the `compoundVariants` key. You can also target **multiple** variants at once. ### Default variants You can also add a default variant to a component. This is useful when you want to add a predefined variants values to a component. ComparisonSlots --- ## Page: https://www.tailwind-variants.org/docs/slots Slots allows you to separate a component into multiple parts. ### Basic Usage You can add slots by using the `slots` key. There's no limit to how many slots you can add. ### Slots with variants You can also change the entire component and its slots by using the `variants`. See more about variants here.  ## Nike Adapt BB 2.0 $279.97 $350 20% off XS S M L XL Select color: Primary Secondary Success **React Example:** ### Slots with compound variants Like variants, you can also define the styles for each slot when using compound variants. The slots can be passed to `class` or `className` as an object. Oops, something went wrong Something went wrong saving your changes. Try again later. Select severity: Success Error Select variant: Filled Outlined **React Example:** ### Compound slots Compound slots allow apply classes to multiple slots at once. This avoids having to repeat the same classes in multiple slots. Can I do the same with variants? ### Slot variant overrides Some component libraries use class render props to allow customizing the class name of a component based on internal state. Tailwind Variants supports slot level variant overrides to make it simple to override the selected variant(s) per slot as necessary. VariantsOverriding Styles --- ## Page: https://www.tailwind-variants.org/docs/overriding-styles Docs Overriding Styles All **Tailwind Variants** components provide an optional `class` / `className` for overriding classes on any component. ### Overriding styles on a single component import { tv } from 'tailwind-variants'; const button = tv({ base: 'font-semibold text-white py-1 px-3 rounded-full active:opacity-80', variants: { color: { primary: 'bg-blue-500 hover:bg-blue-700', secondary: 'bg-purple-500 hover:bg-purple-700', success: 'bg-green-500 hover:bg-green-700', error: 'bg-red-500 hover:bg-red-700' } } }); button({ color: 'secondary', class: 'bg-pink-500 hover:bg-pink-500' // overrides the color variant }); /** * Result: * font-semibold text-white py-1 px-3 rounded-full active:opacity-80 bg-pink-500 hover:bg-pink-500 */ ### Overriding styles on a component with slots  > “Tailwind variants allows you to reduce repeated code in your project and make it more readable. They fixed the headache of building a design system with TailwindCSS.” Zoey Lang Full-stack developer, HeroUI import { tv } from 'tailwind-variants'; const card = tv({ slots: { base: 'md:flex bg-slate-100 rounded-xl p-8 md:p-0 dark:bg-gray-900', avatar: 'w-24 h-24 md:w-48 md:h-auto md:rounded-none rounded-full mx-auto drop-shadow-lg', wrapper: 'flex-1 pt-6 md:p-8 text-center md:text-left space-y-4', description: 'text-md font-medium', infoWrapper: 'font-medium', name: 'text-sm text-sky-500 dark:text-sky-400', role: 'text-sm text-slate-700 dark:text-slate-500' } }); const { base, avatar, wrapper, description, infoWrapper, name, role } = card(); return ( <figure className={base({ class: 'bg-purple-100 dark:bg-purple-800' })}> <img className={avatar()} src="/intro-avatar.png" alt="" width="384" height="512" /> <div className={wrapper()}> <blockquote> <p className={description()}> “Tailwind variants allows you to reduce repeated code in your project and make it more readable. They fixed the headache of building a design system with TailwindCSS.” </p> </blockquote> <figcaption className={infoWrapper()}> <div className={name({ class: 'text-purple-500 dark:text-purple-200' })} > Zoey Lang </div> <div className={role({ class: 'dark:text-purple-100' })}> Full-stack developer, HeroUI </div> </figcaption> </div> </figure> ); SlotsComposing Components --- ## Page: https://www.tailwind-variants.org/docs/composing-components **Tailwind Variants** allows you to easily compose components using the `extend` prop or the resultant function. ### Using the extend prop The `extend` prop allows you to extend the component including its `variants`, `slots`, `defaultVariants` and `compoundVariants`. It automatically merges the values of same keys and offers Typescript autocomplete. #### Basic example #### Extending components with variants Components with `variants` will inherit their variants when composed. You can also extend components with `defaultVariants` and `compoundVariants`. #### Extending components with slots Components with `slots` will inherit their slots when composed.  > “Tailwind variants allows you to reduce repeated code in your project and make it more readable. They fixed the headache of building a design system with TailwindCSS.” Zoey Lang Full-stack developer, HeroUI ### Using the result You can use the result of the `tv()` function to compose your components. However this method is not type-safe and you will have to use the `class` / `className` prop to pass the result to the new component. You can utilize either the `base` key, `slots`, or `variants` when composing components using the result string. The key you use should be in the form of a string array. Overriding StylesExamples --- ## Page: https://www.tailwind-variants.org/docs/examples The following examples will show you how to use the `tailwind-variants` in your project and what you can do with it. ### Installation > Require: `tailwindcss` using in your project. ### Usage Basic usage of `tailwind-variants` is very simple it show `color` and `size` variants and how to use them. ### Adding variants You can add variants by using the `variants` key. There's no limit to how many variants you can add. More details can be found in the Variants page. ### Slots You can add slots by using the `slots` key. There's no limit to how many slots you can add. More details can be found in the Slots page. ### Overriding styles All **Tailwind Variants** components provide an optional `class` / `className` for overriding classes on any component. More details can be found in the Overriding Styles page. ### Composing components **Tailwind Variants** allows you to easily compose components using the `extend` prop or the resultant function. The `extend` prop allows you to extend the component including its `variants`, `slots`, `defaultVariants` and `compoundVariants`. It automatically merges the values of same keys and offers Typescript autocomplete. More details can be found in the Composing Components page. Composing ComponentsTypescript --- ## Page: https://www.tailwind-variants.org/docs/typescript Docs Typescript **Tailwind Variants** provides typing out of the box, but this page contains some further utilities and tips. ### Extract variants from a component You can use the `VariantProps` utility to extract variants from a component. import { tv, type VariantProps } from 'tailwind-variants'; export const button = tv({ base: 'px-4 py-1.5 rounded-full hover:opacity-80', variants: { color: { primary: 'bg-blue-500 text-white', neutral: 'bg-zinc-500 text-black dark:text-white' }, flat: { true: 'bg-transparent' } }, defaultVariants: { color: 'primary' }, compoundVariants: [ { color: 'primary', flat: true, class: 'bg-blue-500/40' }, { color: 'neutral', flat: true, class: 'bg-zinc-500/20' } ] }); /** * Result: * color?: "primary" | "neutral" * flat?: boolean */ type ButtonVariants = VariantProps<typeof button>; interface ButtonProps extends ButtonVariants { children: React.ReactNode; } export const Button = (props: ButtonProps) => { return <button className={button(props)}>{props.children}</button>; }; ### Required variants **Tailwind Variants** doesn't offer a way to make variants required yet, but you can use TypeScript's Utility Types (opens in a new tab) to achieve this. import { tv, type VariantProps } from 'tailwind-variants' const buttonStyles = tv({ base: "px-4 py-1.5 rounded-full hover:opacity-80", variants: { color: { primary: "bg-blue-500 text-white", neutral: "bg-zinc-500 text-black dark:text-white", }, requiredFlat: { true: "bg-transparent", false: "bg-white", }, }, defaultVariants: { color: "primary", }, compoundVariants: [...], }); /** * Result: * color?: "primary" | "neutral" * flat?: boolean */ type ButtonVariants = VariantProps<typeof buttonStyles> export interface ButtonProps extends Omit<ButtonVariants, "requiredFlat">, Required<Pick<ButtonVariants, "requiredFlat">> {} export const button = (props: ButtonProps) => buttonStyles(props); // ❌ TypeScript Error: // Argument of type "{}": is not assignable to parameter of type "ButtonProps". // Property "requiredFlat" is missing in type "{}" but required in type "ButtonProps". button({}); // ✅ button({ requiredFlat: true }); ExamplesConfig --- ## Page: https://www.tailwind-variants.org/docs/config Tailwind Variants has several ways to specify config options: 1. Passing config to the `tv` function 2. Creating a custom `tv` instance using `createTV` 3. Modifying the `defaultConfig` variable ### Local Config The easiest way to configure Tailwind Variants is using the second argument of the `tv` function. This will set the configuration for this specific `tv` call and is useful for one-off config changes. ### Global config If you want your config to apply to all usages of `tv`, you can modify the `defaultConfig` variable to set global configuration for all calls of `tv`. ### Custom `tv` instance If you have different configs for different use cases, the default config might not work for you. Instead, you can use the `createTV` function to create an instance of `tv` with the specified config. ## Config Options ### `twMerge` **description:** Whether to merge class names with the `tailwind-merge` library. It avoids having duplicate tailwind classes. (Recommended) see more here (opens in a new tab) **type:** `boolean` **default**: `true` ### `twMergeConfig` **description:** The config object for `tailwind-merge` library. see more here (opens in a new tab) **type:** `TwMergeConfig` **default**: `{}` TypescriptAPI Reference --- ## Page: https://www.tailwind-variants.org/docs/api-reference Here's the API reference for the `tailwind-variants` exported types and functions. ### Options The `options` argument is an object with the following properties: #### `extend` **description:** This property allows you to extend the `base` styles, `slots`, `variants`, `defaultVariants` and `compoundVariants` from another component. **type:** TVReturnType | `undefined` **default**: `undefined` To learn more about Components composition, check out this page. #### `base` **description:** This property allows you to define the base styles for the component. **type:** ClassValue **default**: `undefined` #### `slots` **description:** This property allows you to define the slots for the component. **type:** `Record<string, ClassValue>` | `undefined` **default**: `{}` To learn more about slots and how to use them, check out the Slots page. #### `variants` **description:** This property allows you to define the variants for the component. **type:** `Record<string, Record<string, ClassValue>>` | `undefined` **default**: `{}` To learn more about variants and how to use them, check out the Variants page. #### `defaultVariants` **description:** This property allows you to define the default variants for the component. **type:** `Record<string, ClassValue>` | `undefined` **default**: `{}` To learn more about default variants and how to use them, check out the Default Variants page. #### `compoundVariants` **description:** This property allows you to define the compound variants for the component. **type:** `Array<Record<string, string> & ClassProp>` | `undefined` **default**: `[]` To learn more about compound variants and how to use them, check out the Compound Variants page. #### `compoundSlots` **description:** This property allows you to define the compound slots for the component. **type:** `Array<Record<string, string> & ClassProp>` | `undefined` **default**: `[]` To learn more about compound slots and how to use them, check out the Compound Slots page. ### Config (optional) The `config` argument is an object with the following properties: #### `twMerge` **description:** Whether to merge the class names with `tailwind-merge` library. It's avoid to have duplicate tailwind classes. (Recommended) see more here (opens in a new tab) **type:** `boolean` **default**: `true` #### `twMergeConfig` **description:** The config object for `tailwind-merge` library. see more here (opens in a new tab) **type:** `TwMergeConfig` **default**: `{}` ### Types #### ClassValue #### ClassProp #### TVReturnType ConfigAcknowledgements --- ## Page: https://www.tailwind-variants.org/docs/acknowledgements Docs Acknowledgements **Tailwind Variants** is heavily inspired by Stitches (opens in a new tab) and CVA (opens in a new tab). * **Stitches** (opens in a new tab) (Modulz (opens in a new tab)) The pioneers of the `variants` API movement. Inmense thanks to Modulz (opens in a new tab) for their work on Stitches and the community around it. 🙏 * **cva** (opens in a new tab) (Joe Bell (opens in a new tab)) This project as started as an extension of Joe's work on `cva` – a great tool for generating variants for a single element with Tailwind CSS. Big shoutout to Joe Bell (opens in a new tab) and contributors (opens in a new tab) you guys rock! 🤘 - we recommend to use `cva` if don't need any of the features listed here (opens in a new tab). API ReferenceFAQ --- ## Page: https://www.tailwind-variants.org/docs/faq This page is a work in progress. If you have any questions, please ask in the Discord .