// Create a

);
}
`

This is what you'll see in your browser:

!Tailwind Compose example usage

Open in CodeSandbox

Conditional Styles / Component Variants

When creating your composed components, you may need to apply certain classes only when the component has a specific prop state. To achieve this, the composer callback accepts a function as its only argument (named here conditional) that takes both a class and a callback that must return a value that evaluates to either true or false based on the component's available props.

If the expression is true, the class is added; if it is false, it is not. Simple!

See the conditional API Reference for more details.

`jsx
const Button = compose.button((conditional) => [
'bg-red-500',
'text-red-50',
conditional('text-xl', ({ $isLarge }) => $isLarge),
]);

// outputs

// outputs
`

Alternatively, you can use the shorthand Tuple syntax and omit the call to the conditional function.

`jsx
const Button = compose.button(() => [
'bg-red-500',
'text-red-50',
['text-xl', ({ $isLarge }) => $isLarge],
]);
`

The conditional function can also instead take an array of classes, which can be combined with other conditional definitions to build up a series of variant states that your component can take on.

`jsx
const Button = compose.button((conditional) => [
conditional(
[
'bg-red-500',
'text-red-50',
],
({ $isSecondary }) => !$isSecondary
),
conditional(
[
'bg-blue-500',
'text-blue-50',
],
({ $isSecondary }) => $isSecondary
),
]);

// outputs

// outputs
`

$3

To prevent props that are only meant to be consumed by your composed components from being passed to the underlying React node or rendered to the DOM element, you can prefix them with a dollar sign ($), turning them into a transient prop.

In the above example, $isSecondary is not rendered to the final DOM element.

Extending Components

As you start to build out your component library, you may wish to use a component but slightly change or build upon its styling. While you could use conditional classes and props to do this, depending on how many alterations you make, this could quickly become unmaintainable.

To simplify the process, you can just extend an existing composed component and supply it with a list of additional classes you wish to attach, resulting in a new component that is the best of both worlds.

`jsx
const Button = compose.button(() => [
'bg-red-500',
'text-red-50',
]);
// outputs

const BorderedButton = compose(Button, () => [
'border',
'border-red-700'
]);
// outputs


`

This also works for custom components, as long as they pass the className prop to a DOM element.

`jsx
function CustomButton({ children, className }) {
return

{children};
}

const ComposedCustomButton = composed(CustomButton, () => [
'bg-red-500',
'text-red-50',
]);


// outputs
`

You can also pass extra classes to individual component instances at runtime via the className prop.

`jsx



// outputs
`

Using as

All composed components are polymorphic, meaning you are able to alter the way they render after they have been created by using the as prop. This keeps all the styling that has been applied to a component but just switches out what is ultimately being rendered (be it a different HTML element or a different custom component).

`jsx
const Button = compose.button(() => [ ... ]);

// This component will render as a div element instead of a button



`

Using attrs

Occasionally, you may know ahead of time if your component will always use the same static prop values, such as an input element having a set type property. By using the attrs method, you can implicitly set any static prop values that should be passed down to every instance of your component.

Furthermore, you can also use the attrs method to attach default values for your dynamic transient props.

`jsx
const TextField = compose.input.attrs({ $hasIcon: false, type: 'text' })(() => [ ... ]);

// This will render with the type attribute implicitly set
// from the original declaration


// You can also locally override any attributes that are defined above

`

`jsx
// For extended components, you can define attributes in the same way
const EmailField = styled(TextField, () => [ ... ]).attrs({ type: 'email' });
`

The attrs method also accepts a callback function that receives the props that the composed component will receive. The return value of this function will be merged into the resulting props.

`jsx
const Button = compose.button.attrs((props) => ({ $size: props.$size }))(() => [ ... ]);

`

tailwind-compose Without Tailwind CSS

Despite the name, tailwind-compose can be used entirely without Tailwind CSS. At its core, tailwind-compose is just a string concatenation library meaning, you can use any utility-first CSS framework of choice or even just your own classes!

`jsx
import styles from './styles.css';

const Button = compose.button(() => [
styles.button,
'our-custom-class',
'whatever-you-want-to-concatenate'
]);


// outputs
`

No React? No Problem!

While primarily designed to be used within React-based projects, tailwind-compose also exports its underlying string concatenation functionality as a standalone method. This means you can bring tailwind-compose into projects of all flavours and retain all of its great features.

`jsx
import { classnames } from 'tailwind-compose';

const button = classnames((conditional) => [
'bg-red-500',
'text-red-50',
conditional('text-xl', ({ isLarge }) => isLarge),
]);

button();
// outputs "bg-red-500 text-red-50"

button({ isLarge: true });
// outputs "bg-red-500 text-red-50 text-xl"
`

Execution Hooks

Inspired by Joe Bell's work on cva.

tailwind-compose allows you to perform additional custom logic to the concatenated class string by defining a global event handler for the onDone event. This can be particularly useful if you want to combine tailwind-compose with a utility function such as tailwind-merge.

$3

`jsx
// tailwind-compose.config.ts

import { DefineConfigOptions, defineConfig } from 'tailwind-compose';
import { twMerge } from 'tailwind-merge';

const config: DefineConfigOptions = {
hooks: {
onDone: (className) => twMerge(className),
},
};

export const { classname, compose } = defineConfig(config);
`

`jsx
// components/button.ts

import { classnames, compose } from '../tailwind-compose.config';

const button = classnames(() => [
'bg-orange-100',
'bg-red-500',
]);

const Button = compose.button(() => [
'bg-orange-100',
'bg-red-500',
]);

button();
// outputs "bg-red-500"


// outputs
`

TypeScript Support

tailwind-compose has first-class type definition support, making it super easy to get started with your TypeScript project.

Any composed component that you create will infer the underlying base HTML element and attach the appropriate attribute types to it. This means your IDE's Intellisense can autocomplete all available props against your component, ensuring you or your peers are never in the dark.

`jsx
const MyInput = compose.input(() => [ ... ]);

// Returns the following TypeScript type:
// ComposedComponent<
// React.ClassAttributes & React.InputElementAttributes &
// Props
// >
`

If you want to ensure that any custom props are type-safe, you can pass your Type Assertions in the following way:

`jsx
interface ButtonProps {
$size: 'small' | 'large';
}

const Button = compose.button(() => [ ... ]);
// OR
const Button = compose<'button', ButtonProps>('button', () => [ ... ]);

// Oops! This will throw a type error because the size prop has not been defined


// Life in beautiful type-safe harmony


`

Additionally, extended components have their types transferred to your newly created composed variant.

`jsx
interface ExampleComponentProps {
className?: string;
icon: 'tick' | 'cross';
large: boolean;
}

function ExampleComponent({ className, icon, large }: ExampleProps) {
return (






);
}

const ComposedExampleComponent = composed(ExampleComponent, () => [ ... ]);

// Returns the following TypeScript type:
// ComposedComponent
`

Tailwind CSS Intellisense

You can enable autocompletion for tailwind-compose using the following steps below:

$3

1. Install the "Tailwind CSS IntelliSense" Visual Studio Code extension.
1. Add the following to your settings.json:

`json
{
"tailwindCSS.experimental.classRegex": [
[
"(?:classnames|compose).+\\[((?:.|\n)*?)\\]\\)",
"\"'[\"']"
]
],
}
`

$3

1. Install the Tailwind CSS Language Server extension.
1. Add the following configuration:

`lua
lspconfig.tailwindcss.setup({
settings = {
tailwindCSS = {
experimental = {
classRegex = {
{
"(?:classnames|compose).+\\[((?:.|\n)*?)\\]\\)",
"\"'[\"']"
},
},
},
},
},
})
`

$3

1. Check the version. Available for WebStorm 2023.1 and later.
1. Open the settings and go to Languages and Frameworks | Style Sheets | Tailwind CSS.
1. Add the following to your Tailwind CSS configuration:

`json
{
"experimental": {
"classRegex": [
"(?:classnames|compose).+\\[((?:.|\n)*?)\\]\\)",
"\"'[\"']"
]
}
}
`

API Reference

#### compose

`jsx
/**
* Create a composed component from a variable target
* @param {string | ComposedComponent | React.ComponentType} element
* @param {composer} composer
* @returns {ComposedComponent}
*/
const Component = compose(element, composer);
`

`jsx
/**
* Create a composed component from a set element
* @param {composer} composer
* @returns {ComposedComponent}
*/
const Component = compose.div(composer);
`

#### compose.attrs

`jsx
/**
* Create a composed component from a variable target w/ defined static attributes
* @param {object | attrsFactory} attributes
* @param {string | ComposedComponent | React.ComponentType} element
* @param {composer} composer
* @returns {ComposedComponent}
*/
const Component = compose(element, composer).attrs(attributes);
`

`jsx
/**
* Create a composed component from a set element w/ defined static attributes
* @param {object | attrsFactory} attributes
* @param {composer} composer
* @returns {ComposedComponent}
*/
const Component = compose.div.attrs(attributes)(composer);
`

#### compose.toClass

`jsx
const Component = compose(element, composer);
// OR
const Component = compose.div(composer);

/**
* Create a composed classlist from an existing composed component
* @param {object=} props
* @returns {string}
*/
const classlist = Component.toClass(props);
`

#### classnames

`jsx
/**
* Create a composed classlist
* @param {composer} composer
* @returns {string}
*/
const Component = classnames(composer);
`

#### defineConfig

`jsx
/**
* Generate a set of tailwind-compose functions with custom configurations
* @param {object} config
* @param {object} config.hooks.onDone
* @returns {object}
*/
const { classnames, compose } = defineConfig(config);
`

---

#### composer

`jsx
/**
* Callback to create a composed classlist
* @callback composer
* @param {conditional=} conditional
* @returns {string[]}
*/
const composer = (conditional) => classes;
`

#### attrsFactory

`jsx
/**
* Callback to create an attributes object
* @callback attrsFactory
* @param {object=} props
* @returns {object}
*/
const attrsFactory = (props) => props;
`

#### conditional

`jsx
/**
* Syntactic sugar to compose a conditional classlist tuple
* @param {string | string[]} target
* @param {condition} condition
* @returns {[string | string[], condition]}
*/
const conditional = conditional(target, condition);
`

#### condition

`jsx
/**
* Callback to evaluate whether a given condition is truthy
* @callback condition
* @param {object=} props
* @returns {boolean}
*/
const condition = (props) => boolean;
`

Browser Support

tailwind-compose should work in all major modern browsers out-of-the-box (Chrome, Edge, Firefox, Safari).

To add support for browsers IE 11 and older, ensure you add polyfills for the following features:

- Object.assign()
- Proxy

Badge

Sing loud and proud! Let the world know that you're using tailwind-compose.

![styled with: tailwind-compose](https://github.com/eels/tailwind-compose)

`
![styled with: tailwind-compose](https://github.com/eels/tailwind-compose)
`

Contributing

Thanks for taking the time to contribute! Before you get started, please take a moment to read through our contributing guide. The two focus areas for tailwind-compose right now are increasing performance and fixing potential bugs.

However, all issues and PRs are welcome!

Alternative Packages

This package was primarily designed to meet my own personal goals for working with Tailwind CSS and may not be the right solution for you and your project. If that is the case, here's a short list of alternative packages to consider that may better suit your needs if tailwind-compose` is not for you.

- clb
- clsx
- cva
- twnd

License

MIT - see the LICENSE.md file for details.

Acknowledgments

- Originally inspired by parts of the styled-components API
- With additional optimisation inspiration from the 1KB alternative, goober