tailwind-variants

What is tailwind-variants?

The tailwind-variants npm package is designed to help developers create and manage variants of Tailwind CSS classes more efficiently. It allows for the dynamic generation of class names based on different states, conditions, and themes, making it easier to maintain and scale Tailwind CSS projects.

What are tailwind-variants's main functionalities?

Dynamic Class Generation

This feature allows you to dynamically generate class names based on different variants. In this example, the `button` object can generate classes for different sizes and colors of a button.

const button = tv({ base: 'px-4 py-2 font-bold', variants: { size: { small: 'text-sm', large: 'text-lg' }, color: { primary: 'text-white bg-blue-500', secondary: 'text-gray-700 bg-gray-200' } } });

Conditional Class Application

This feature allows you to apply classes conditionally based on the provided variants. In this example, the `buttonClass` will generate the appropriate class string based on the `size` and `color` variants.

const buttonClass = button({ size: 'large', color: 'primary' }); // 'px-4 py-2 font-bold text-lg text-white bg-blue-500'

Theme Support

This feature allows you to define and apply different themes to your components. In this example, the `themedButton` object can generate classes for light and dark themes.

const themedButton = tv({ base: 'px-4 py-2 font-bold', variants: { theme: { light: 'text-black bg-white', dark: 'text-white bg-black' } } });

Other packages similar to tailwind-variants

clsx

clsx is a utility for constructing `className` strings conditionally. It is similar to tailwind-variants in that it helps manage class names dynamically, but it does not provide built-in support for Tailwind CSS variants or themes.

classnames

classnames is another utility for conditionally joining class names together. Like clsx, it helps manage class names dynamically but lacks the specific Tailwind CSS variant and theme support provided by tailwind-variants.

twin.macro

twin.macro is a library that allows you to use Tailwind CSS with styled-components or emotion. It provides a way to manage Tailwind CSS classes within JavaScript, but it focuses more on integrating Tailwind with CSS-in-JS solutions rather than managing variants and themes.

README

tailwind-variants

The power of Tailwind combined with a first-class variant API.

Features

• First-class variant API
• Responsive variants
• Slots support
• Composition support
• Fully typed
• Framework agnostic
• Automatic conflict resolution

Documentation

For full documentation, visit tailwind-variants.org

Quick Start

1. Installation: To use Tailwind Variants in your project, you can install it as a dependency:

yarn add tailwind-variants
# or
npm i tailwind-variants

1. Usage:

import { tv } from 'tailwind-variants';
 
const button = tv({
  base: "font-medium bg-blue-500 text-white rounded-full active:opacity-80",
  variants: {
    color: {
      primary: "bg-blue-500 text-white",
      secondary: "bg-purple-500 text-white",
    },
    size: {
      sm: "text-sm",
      md: "text-base",
      lg: "px-4 py-3 text-lg",
    },
  },
  compoundVariants: [
    {
      size: ["sm", "md"],
      class: "px-3 py-1",
    },
  ],
  defaultVariants: {
    size: "md",
    color: "primary",
  }
});
 
return (
  <button className={button({ size: 'sm', color: 'secondary' })}>Click me</button>
)

1. Responsive variants configuration (optional): If you want to use responsive variants you need to add the Tailwind Variants wrapper to your TailwindCSS config file tailwind.config.js.

// tailwind.config.js
 
const { withTV } = require('tailwind-variants/transformer')

/** @type {import('tailwindcss').Config} */
module.exports = withTV({
  content:  ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
  theme: {
    extend: {},
  },
  plugins: [],
})

If you're using a custom path to import Tailwind variants, such as creating a custom tv instance with createTV, it's recommended to include this path in the transformer configuration:

// tailwind.config.js

const { withTV } = require('tailwind-variants/transformer')

/** @type {import('tailwindcss').Config} */
module.exports = withTV({
  content:  ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
  theme: {
    extend: {},
  },
  plugins: [],
}, {
  aliases: ["@/lib/tv"]
})

Acknowledgements

• cva (Joe Bell) 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 and contributors you guys rock! 🤘 - we recommend to use cva if don't need any of the Tailwind Variants features listed here.

• Stitches (Modulz)
  The pioneers of the variants API movement. Inmense thanks to Modulz for their work on Stitches and the community around it. 🙏

Community

We're excited to see the community adopt NextUI, raise issues, and provide feedback. Whether it's a feature request, bug report, or a project to showcase, please get involved!

• Discord
• Twitter
• GitHub Discussions

Contributing

Contributions are always welcome!

Please follow our contributing guidelines.

Please adhere to this project's CODE_OF_CONDUCT.

Authors

• Junior garcia (@jrgarciadev)
• Tianen Pang (@tianenpang)

License

Licensed under the MIT License.

See LICENSE for more information.