Tailwind Variants

https://www.tailwind-variants.org/docs
Admin
Tailwind Variants is a first-class variant API library for TailwindCSS that enables creating...
Tokens:22,768
Snippets:214
Trust Score:8.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Get Page Tool Example

Source: https://www.tailwind-variants.org/docs/mcp-server

Example arguments for the get_page tool. The path parameter accepts a full path like /docs/variants, a slug like variants, or a page name like slots.

```json
{ "path": "/docs/slots" }
```

--------------------------------

### Search Docs Tool Example

Source: https://www.tailwind-variants.org/docs/mcp-server

Example arguments for the search_docs tool. The query parameter performs full-text search across title, description, URL, and page body.

```json
{ "query": "slots" }
```

--------------------------------

### createTV with default config

Source: https://www.tailwind-variants.org/docs/api-reference

Creates a tv function with default configuration. The example enables twMerge and shows an extend config placeholder.

```ts
const tv = createTV({
  twMerge: true,
  twMergeConfig: { extend: { /* ... */ } }
});
```

--------------------------------

### Install tailwind-variants with npm

Source: https://www.tailwind-variants.org/docs/quick-start

Install the default build of Tailwind Variants. Conflict resolution is included, so tailwind-merge is not needed unless called directly.

```bash
npm install tailwind-variants
```

--------------------------------

### Framework-agnostic tv recipe

Source: https://www.tailwind-variants.org/docs/quick-start

Define a recipe with tv that can be used with any framework or vanilla JS. The example shows a button with color variants and default variant.

```ts
import { tv } from "tailwind-variants";

const button = tv({
  base: "inline-flex cursor-pointer items-center justify-center rounded-md px-4 py-2 text-sm font-medium select-none",
  variants: {
    color: {
      primary: "bg-blue-600 text-white",
      secondary: "bg-zinc-200 text-zinc-900",
    },
  },
  defaultVariants: {
    color: "primary",
  },
});
```

--------------------------------

### GET /llms-full.txt

Source: https://www.tailwind-variants.org/docs/llms-txt

Returns the complete documentation set in a single Markdown file.

```APIDOC
## GET /llms-full.txt

### Description
Returns the entire documentation corpus in a single Markdown file.

### Method
GET

### Endpoint
/llms-full.txt

### Response
#### Success Response (200)
- **Content-Type**: `text/markdown`
- **Body**: Full Markdown corpus of all documentation pages.

#### Response Example
```
# Full Docs
...
```

```

--------------------------------

### Per-page Markdown URLs

Source: https://www.tailwind-variants.org/docs/llms-txt

Example URLs for fetching individual documentation pages as Markdown. Each response contains the page title, URL, and Markdown body with demos expanded to code fences.

```text
/docs/quick-start.md
/docs/slots.md
/docs/api-reference.md
```

--------------------------------

### Create a button recipe with tv

Source: https://www.tailwind-variants.org/docs/quick-start

Define a recipe with tv and call it as a function. Defaults keep call sites short; pass props only when needed. The example shows a button with variants for variant and size, and default variants.

```tsx
import { tv } from 'tailwind-variants';

const button = tv({
  base: 'inline-flex cursor-pointer items-center justify-center rounded-full font-medium select-none transition-colors',
  variants: {
    variant: {
      primary: 'bg-zinc-900 text-white hover:bg-zinc-800',
      secondary: 'border border-zinc-300 bg-zinc-50 text-zinc-900 hover:bg-zinc-100',
      tertiary: 'text-zinc-700 hover:bg-zinc-200/70 hover:text-zinc-950'
    },
    size: {
      sm: 'h-8 px-3 text-sm',
      md: 'h-10 px-4 text-sm'
    }
  },
  defaultVariants: {
    variant: 'primary',
    size: 'md'
  }
});

<button className={button()}>Default button</button>
<button className={button({ variant: 'secondary', size: 'sm' })}>
  Click me
</button>
<button className={button({ class: 'w-full' })}>Full width</button>
```

--------------------------------

### cx() usage example

Source: https://www.tailwind-variants.org/docs/api-reference

Shows cx() performing lightweight concatenation without conflict resolution. Available in both default and lite builds; replaces deprecated cnBase.

```ts
cx('text-blue-500', 'text-red-500'); // => "text-blue-500 text-red-500"
```

--------------------------------

### GET /llms.txt

Source: https://www.tailwind-variants.org/docs/llms-txt

Fetches the curated index of documentation pages as Markdown.

```APIDOC
## GET /llms.txt

### Description
Returns a curated index of the entire documentation: a project summary plus links to every docs page's Markdown URL.

### Method
GET

### Endpoint
/llms.txt

### Response
#### Success Response (200)
- **Content-Type**: `text/markdown`
- **Body**: Markdown index of all documentation pages.

#### Response Example
```
# LLMs.txt
## Project summary
...
```

```

--------------------------------

### GET /docs/{slug}

Source: https://www.tailwind-variants.org/docs/llms-txt

Returns the standard documentation page, with content negotiation allowing Markdown responses.

```APIDOC
## GET /docs/{slug}

### Description
Returns the normal HTML documentation page. When the `Accept` header prefers Markdown, the same body as `/docs/{slug}.md` is returned.

### Method
GET

### Endpoint
/docs/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The documentation page identifier, e.g., `variants`.

#### Request Headers
- **Accept** (string) - Optional - Content negotiation header; e.g., `text/markdown` to receive Markdown.

### Response
#### Success Response (200)
- **Content-Type**: `text/html` (default) or `text/markdown` when `Accept` prefers it.
- **Body**: Normal documentation page or Markdown version, depending on the `Accept` header.

#### Response Example
When `Accept: text/markdown`, response is:
```
# Page Title
...markdown content...
```

```

--------------------------------

### Responsive slot classes with sm: and md: prefixes

Source: https://www.tailwind-variants.org/docs/responsive

Use responsive breakpoint prefixes inside slot class strings. The event example shows how slots like root, time, body, and place respond at sm and md breakpoints, and destructures the resulting slot class names.

```ts
import { tv } from 'tailwind-variants';

const event = tv({
  slots: {
    root: [
      'flex flex-col gap-3.5 rounded-xl border p-3.5 sm:p-4',
      'md:flex-row md:items-center md:gap-4'
    ],
    time: [
      'flex w-fit flex-col self-start rounded-lg bg-zinc-100 px-3 py-2.5',
      'md:min-w-[4.5rem] md:items-center md:self-auto md:px-2.5 md:py-3'
    ],
    hour: 'text-sm font-semibold tracking-tight sm:text-[0.9375rem]',
    day: 'mt-0.5 text-[0.6875rem] text-zinc-500',
    body: [
      'flex min-w-0 flex-1 flex-col gap-0.5',
      'sm:flex-row sm:items-baseline sm:gap-2',
      'md:flex-col md:items-stretch md:gap-0.5'
    ],
    title: 'shrink-0 text-[0.875rem] font-medium sm:text-[0.9375rem]',
    place: [
      'min-w-0 text-[0.75rem] text-zinc-500',
      'sm:truncate sm:text-[0.8125rem]',
      'md:overflow-visible md:text-clip'
    ],
    actions: 'flex w-full gap-2 md:w-auto md:shrink-0'
  }
});

const { root, time, hour, day, body, title, place, actions } = event();
```

--------------------------------

### Define base styles and variant keys with tv()

Source: https://www.tailwind-variants.org/docs/variants

Creates a button recipe with a base style and a `variant` key with three options. Call the recipe with `{ variant: 'secondary' }` to get the combined classes. Base classes apply first, variant classes layer on top, and conflicting utilities resolve automatically.

```TypeScript
import { tv } from 'tailwind-variants';

const button = tv({
  base: 'inline-flex cursor-pointer items-center justify-center rounded-full px-4 py-2 text-sm font-medium select-none transition-colors',
  variants: {
    variant: {
      primary: 'bg-zinc-900 text-white hover:bg-zinc-800',
      secondary: 'border border-zinc-300 bg-zinc-50 text-zinc-900 hover:bg-zinc-100',
      tertiary: 'text-zinc-700 hover:bg-zinc-200/70 hover:text-zinc-950'
    }
  }
});

button({ variant: 'secondary' });
```

--------------------------------

### GET /docs/{slug}.md

Source: https://www.tailwind-variants.org/docs/llms-txt

Fetches a single documentation page converted to Markdown, with a stable URL for tooling.

```APIDOC
## GET /docs/{slug}.md

### Description
Fetches a single documentation page as Markdown, with demos expanded to code fences. The slug corresponds to a documentation topic, such as `quick-start`, `slots`, or `api-reference`.

### Method
GET

### Endpoint
/docs/{slug}.md

### Parameters
#### Path Parameters
- **slug** (string) - Required - The documentation page identifier, e.g., `quick-start`.

### Response
#### Success Response (200)
- **Content-Type**: `text/markdown`
- **Body**: Markdown page content with page title, URL, and body.

#### Response Example
```
# Page Title
URL: https://example.com/docs/slug

...body...
```

```

--------------------------------

### Upgrade: remove tailwind-merge from install

Source: https://www.tailwind-variants.org/docs/releases

Upgrade step showing the removal of tailwind-merge from the install command when it was only used for TV. The diff indicates the old line (with tailwind-merge) is removed and the new line (without it) is added.

```diff
- npm i tailwind-variants tailwind-merge
+ npm i tailwind-variants
```

--------------------------------

### Responsive class overrides at the call site

Source: https://www.tailwind-variants.org/docs/responsive

Override classes at the call site also accept responsive utilities. This example passes a class override with w-full and sm:w-auto to a button component.

```ts
button({
  variant: 'primary',
  class: 'w-full sm:w-auto'
});
```

--------------------------------

### Responsive styles in base with Tailwind breakpoint prefixes

Source: https://www.tailwind-variants.org/docs/responsive

Use Tailwind breakpoint prefixes (sm:, md:) directly in the base class string of a tv() component. No TV-specific responsive API is needed; the styles scale across breakpoints as shown in the stay, media, details, place, and price examples.

```ts
import { tv } from 'tailwind-variants';

const stay = tv({
  base: 'rounded-xl border p-3.5 sm:p-4 md:p-5'
});

const media = tv({
  base: 'flex h-28 items-center justify-center rounded-lg bg-zinc-100 sm:h-36 md:h-40'
});

const details = tv({
  base: [
    'mt-3 flex flex-col gap-2.5',
    'sm:mt-3.5 sm:flex-row sm:items-end sm:justify-between'
  ]
});

const place = tv({
  base: 'text-[0.9375rem] font-semibold tracking-tight sm:text-lg md:text-xl'
});

const price = tv({
  base: 'text-[0.8125rem] sm:shrink-0 sm:text-right sm:text-sm'
});
```

--------------------------------

### cnMerge() usage examples

Source: https://www.tailwind-variants.org/docs/api-reference

Shows cnMerge() concatenating with optional per-call config. The first call merges conflicts, the second disables twMerge. Only available in the default build, not exported from /lite.

```ts
cnMerge('px-2', 'px-4')(); // => "px-4"
cnMerge('px-2', 'px-4')({ twMerge: false }); // => "px-2 px-4"
```

--------------------------------

### Basic compound variant with class and className

Source: https://www.tailwind-variants.org/docs/compound-variants

Defines a button with variant and size axes, then adds compound variants that apply a shadow when both variant and size match. The first compound rule uses `class`, the second uses `className`; both are equivalent. Large primary and secondary buttons get the shadow, while small primary and tertiary buttons do not.

```ts
import { tv } from 'tailwind-variants';

const button = tv({
  base: 'inline-flex cursor-pointer items-center justify-center rounded-full font-medium select-none transition-colors',
  variants: {
    variant: {
      primary: 'bg-zinc-900 text-white',
      secondary: 'border border-zinc-300 bg-zinc-50 text-zinc-900',
      tertiary: 'text-zinc-700'
    },
    size: {
      sm: 'h-8 px-3 text-sm',
      lg: 'h-11 px-6 text-base'
    }
  },
  compoundVariants: [
    {
      variant: 'primary',
      size: 'lg',
      class: 'shadow-lg shadow-zinc-900/20'
    },
    {
      variant: 'secondary',
      size: 'lg',
      className: 'shadow-md shadow-zinc-900/10'
    }
  ]
});
```

--------------------------------

### createTV

Source: https://www.tailwind-variants.org/docs/api-reference

Returns a `tv` with default config.

```APIDOC
## `createTV`

### Description
Returns a `tv` with default config.

### Signature
```ts
createTV(config)
```

### Parameters
- **config** (object) - Required - Configuration object with `twMerge` and `twMergeConfig` properties.

### Return Value
Returns a `tv` function with the provided default config.

### Example
```ts
const tv = createTV({
  twMerge: true,
  twMergeConfig: { extend: { /* ... */ } }
});
```
```

--------------------------------

### Import default vs lite build

Source: https://www.tailwind-variants.org/docs/faq

Shows how to import the default build (with merge) or the lite build (without merge, ~80% smaller).

```ts
import { tv } from 'tailwind-variants';       // merge on
import { tv } from 'tailwind-variants/lite';  // merge off
```

--------------------------------

### Use createTV with lite build

Source: https://www.tailwind-variants.org/docs/configuration

Use createTV with the lite build entry point. The lite build ignores merge either way; use it when config is about API consistency, not merge.

```ts
import { createTV } from 'tailwind-variants/lite';

const tv = createTV({ twMerge: false });
```

--------------------------------

### Import tv from lite build

Source: https://www.tailwind-variants.org/docs/quick-start

Use the lite build for a smaller bundle without merge functionality.

```ts
import { tv } from "tailwind-variants/lite";
```

--------------------------------

### Create tv with createTV and custom twMergeConfig

Source: https://www.tailwind-variants.org/docs/configuration

Create a tv function with baked-in config using createTV. Every recipe created with this tv inherits the same merge settings.

```ts
import { createTV } from 'tailwind-variants';

const tv = createTV({
  twMerge: true,
  twMergeConfig: {
    extend: {
      classGroups: {
        'font-size': ['text-tiny', 'text-small']
      }
    }
  }
});

const button = tv({
  base: 'font-medium',
  variants: {
    size: {
      tiny: 'text-tiny',
      small: 'text-small'
    }
  }
});
```

--------------------------------

### cn() usage examples

Source: https://www.tailwind-variants.org/docs/api-reference

Shows cn() concatenating and merging class names with default config. Returns a string (v3.2.2+). Only available in the default build.

```ts
cn('px-2', 'px-4'); // => "px-4"
cn('text-sm', { 'font-bold': true }); // => "text-sm font-bold"
```

--------------------------------

### Array values for variant classes

Source: https://www.tailwind-variants.org/docs/variants

Variant values can be arrays; TV flattens them like `clsx`. This example defines a `color` variant with an array of classes for the `primary` option.

```TypeScript
const badge = tv({
  base: 'inline-flex select-none items-center rounded-full border px-2.5 py-0.5 text-sm font-medium',
  variants: {
    color: {
      primary: ['bg-zinc-100', 'text-zinc-800', 'border-zinc-300']
    }
  }
});
```

--------------------------------

### Use tv recipe in Solid

Source: https://www.tailwind-variants.org/docs/quick-start

Use the button recipe in a Solid component with class attribute.

```tsx
<button class={button({ color: "primary" })}>Save</button>
```

--------------------------------

### Use tv recipe in vanilla JS

Source: https://www.tailwind-variants.org/docs/quick-start

Use the button recipe in vanilla JavaScript by setting the className property.

```ts
element.className = button({ color: "primary" });
```

--------------------------------

### Slots empty object behavior in v3.3.0

Source: https://www.tailwind-variants.org/docs/migration

In v3.3.0, passing slots: {} enables slot mode with an implicit base slot, so tv returns an object with a base function. Omit slots to get a plain string return.

```ts
// Slot mode — returns { base: () => string }
const x = tv({ slots: {}, base: 'p-4' });

// String mode — omit slots
const y = tv({ base: 'p-4' });
```

--------------------------------

### Extend a recipe with the extend option

Source: https://www.tailwind-variants.org/docs/extending

Shows how to create a new recipe with the `extend` option, inheriting base styles, variants, and defaults from a parent recipe while adding new variant axes like `iconOnly`. The child recipe's `base` is concatenated with the parent's base, and new variants are added without modifying the original.

```ts
import { tv } from 'tailwind-variants';

const baseButton = tv({
  base: 'inline-flex cursor-pointer items-center justify-center rounded-full font-medium select-none transition-colors',
  variants: {
    variant: {
      primary: 'bg-zinc-900 text-white',
      secondary: 'border border-zinc-300 bg-zinc-50 text-zinc-900',
      tertiary: 'text-zinc-700'
    },
    size: {
      sm: 'h-8 px-3 text-sm',
      md: 'h-10 px-4 text-sm'
    }
  },
  defaultVariants: {
    variant: 'primary',
    size: 'md'
  }
});

const iconButton = tv({
  extend: baseButton,
  base: 'gap-2',
  variants: {
    iconOnly: {
      true: 'aspect-square px-0',
      false: ''
    }
  }
});
```

--------------------------------

### Two builds in v2 to v3 migration

Source: https://www.tailwind-variants.org/docs/migration

In v2 to v3, there are two builds: the default build includes conflict resolution (v3.3+) and exports tv, cn, cx; the lite build has no merge and is ~80% smaller, exporting tv and cx.

```ts
// Default — conflict resolution included (v3.3+)
import { tv, cn, cx } from 'tailwind-variants';

// Lite — no merge, ~80% smaller
import { tv, cx } from 'tailwind-variants/lite';
```

--------------------------------

### Import lite build from 'tailwind-variants/lite'

Source: https://www.tailwind-variants.org/docs/api-reference

Import the lite build, which only exports tv and cx.

```ts
import { tv, cx } from 'tailwind-variants/lite';
```

--------------------------------

### tv

Source: https://www.tailwind-variants.org/docs/api-reference

Creates a variant recipe. Returns a callable function plus metadata.

```APIDOC
## `tv`

### Description
Creates a variant recipe. Returns a callable function plus metadata.

### Signature
```ts
tv(options, config?)
```

### Parameters
#### Options
- **extend** (TVReturnType) - Optional - Merge another recipe's base, slots, variants, defaults, compounds
- **base** (ClassValue) - Optional - Shared classes for every call
- **slots** (Record<string, ClassValue>) - Optional - Named parts; `{}` enables implicit `base` slot only
- **variants** (Record<string, Record<string, ClassValue>>) - Optional - Variant axes; per-slot objects when using slots
- **defaultVariants** (Record<string, ClassValue>) - Optional - Values applied when keys are omitted
- **compoundVariants** (Array<Record<string, unknown> & ClassProp>) - Optional - Extra classes when multiple conditions match
- **compoundSlots** (Array<Record<string, unknown> & ClassProp>) - Optional - Extra classes on specific slots when conditions match

#### Config (2nd argument)
- **twMerge** (boolean) - Optional - Enable tailwind merge
- **twMergeConfig** (TwMergeConfig) - Optional - Configuration for tailwind merge

### Return Value
Returns a callable function plus metadata. The callable function accepts variant keys plus optional `class` / `className` overrides.

### Example
```ts
const button = tv(options, config?);

button({ variant: 'primary' }); // => string (no slots)
button({ variant: 'primary' }).base(); // => string (with slots)

button.base;              // resolved base string
button.slots;             // slot class map
button.variants;          // variant definitions
button.variantKeys;       // ['variant', 'size', ...]
button.defaultVariants;   // { variant: 'primary', ... }
button.compoundVariants;  // array
button.compoundSlots;     // array
```
```

--------------------------------

### Override config per recipe with tv second argument

Source: https://www.tailwind-variants.org/docs/configuration

Pass config as the second argument to tv for one-off overrides. Per-recipe config wins over createTV defaults for that instance.

```ts
import { tv } from 'tailwind-variants';

const badge = tv(
  { base: 'rounded-full px-2', variants: { /* ... */ } },
  { twMerge: false }
);
```

--------------------------------

### Use tv recipe in Angular

Source: https://www.tailwind-variants.org/docs/quick-start

Use the button recipe in an Angular template with property binding.

```html
<button [class]="button({ color: 'primary' })">Save</button>
```

--------------------------------

### Setting defaultVariants in a tv() recipe

Source: https://www.tailwind-variants.org/docs/default-variants

Defines a button recipe with `variant` and `size` variants, and sets `defaultVariants` to `variant: 'primary'` and `size: 'md'`. When calling `button()` without arguments, defaults apply; passing `{ size: 'sm' }` overrides only size, keeping variant as primary.

```tsx
import { tv } from 'tailwind-variants';

const button = tv({
  base: 'inline-flex cursor-pointer items-center justify-center rounded-full font-medium select-none transition-colors',
  variants: {
    variant: {
      primary: 'bg-zinc-900 text-white',
      secondary: 'border border-zinc-300 bg-zinc-50 text-zinc-900',
      tertiary: 'text-zinc-700'
    },
    size: {
      sm: 'h-8 px-3 text-sm',
      md: 'h-10 px-4 text-sm'
    }
  },
  defaultVariants: {
    variant: 'primary',
    size: 'md'
  }
});

<button className={button()}>Primary, medium</button>
<button className={button({ size: 'sm' })}>Primary, small</button>
<button className={button({ variant: 'secondary' })}>Secondary, medium</button>
```

--------------------------------

### VS Code IntelliSense configuration for tv

Source: https://www.tailwind-variants.org/docs/quick-start

Add this to your VS Code settings to enable Tailwind CSS IntelliSense to complete classes inside tv strings.

```json
{
  "tailwindCSS.experimental.classRegex": [
    ["tv\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}
```

--------------------------------

### Define a button recipe with tv()

Source: https://www.tailwind-variants.org/docs/introduction

Use the tv() function to define a button recipe with base styles, variants for variant and size, and defaultVariants. Call the returned function with typed props to apply the styles.

```TypeScript
import { tv } from 'tailwind-variants';

const button = tv({
  base: 'inline-flex cursor-pointer items-center justify-center rounded-full font-medium select-none transition-colors',
  variants: {
    variant: {
      primary: 'bg-zinc-900 text-white hover:bg-zinc-800',
      secondary: 'border border-zinc-300 bg-zinc-50 text-zinc-900 hover:bg-zinc-100',
      tertiary: 'text-zinc-700 hover:bg-zinc-200/70 hover:text-zinc-950'
    },
    size: {
      sm: 'h-8 px-3 text-sm',
      md: 'h-10 px-4 text-sm'
    }
  },
  defaultVariants: {
    variant: 'primary',
    size: 'md'
  }
});
```

--------------------------------

### get_page

Source: https://www.tailwind-variants.org/docs/mcp-server

Fetches a documentation page's Markdown content.

```APIDOC
## get_page

### Description
Fetches the full Markdown for a documentation page by path or slug.

### Method
MCP Tool

### Endpoint
https://www.tailwind-variants.org/api/mcp

### Parameters
#### Request Body
- **path** (string) - Required - The page path or slug (e.g., `/docs/variants`, `variants`, or `slots`).

### Request Example
{
  "path": "/docs/slots"
}

### Response
Returns the full Markdown content of the requested page.
```

--------------------------------

### Import main API from 'tailwind-variants'

Source: https://www.tailwind-variants.org/docs/api-reference

Import the main API functions and the VariantProps type from the default build of tailwind-variants.

```ts
import {
  tv,
  createTV,
  cn,
  cnMerge,
  cx,
  type VariantProps
} from 'tailwind-variants';
```

--------------------------------

### Enable slot mode with tv()

Source: https://www.tailwind-variants.org/docs/slots

Enable slot mode by passing a `slots` object to `tv()`. Each key becomes a named slot function on the return value. Pass an explicit empty `slots: {}` to enable slot mode with an implicit `base` slot only; omit `slots` entirely for a plain class string return.

```ts
import { tv } from 'tailwind-variants';

const alert = tv({
  slots: {
    base: 'flex gap-3 rounded-lg p-4',
    icon: 'size-5 shrink-0',
    title: 'font-semibold',
    description: 'text-sm opacity-80'
  }
});

const { base, icon, title, description } = alert();

base();
title();
```

--------------------------------

### cn

Source: https://www.tailwind-variants.org/docs/api-reference

Concatenate and merge with default config. Returns a string.

```APIDOC
## `cn`

### Description
Concatenate and merge with default config. Returns a **string** (v3.2.2+).

### Signature
```ts
cn(...inputs)
```

### Parameters
- **inputs** (ClassValue[]) - Required - Class values to concatenate and merge.

### Return Value
Returns a string with merged classes.

### Example
```ts
cn('px-2', 'px-4'); // => "px-4"
cn('text-sm', { 'font-bold': true }); // => "text-sm font-bold"
```

### Notes
Default build only.
```

--------------------------------

### Cursor MCP Configuration for Local Development

Source: https://www.tailwind-variants.org/docs/mcp-server

Configuration for Cursor's .cursor/mcp.json to connect to a local development instance of the MCP server. Restart Cursor after saving to enable the agent to call list_pages, search_docs, and get_page.

```json
{
  "mcpServers": {
    "tailwind-variants": {
      "url": "http://localhost:3000/api/mcp"
    }
  }
}
```

--------------------------------

### tv (second argument config)

Source: https://www.tailwind-variants.org/docs/class-resolution

The second argument to `tv` accepts a config object to enable Tailwind merge and customize merge behavior.

```APIDOC
## `tv` (second argument config)

### Description
The second argument to `tv` accepts a config object to enable Tailwind merge and customize merge behavior.

### Import
```ts
import { tv } from 'tailwind-variants';
```

### Parameters
- **config** (object) - Optional - Configuration for the variant function.
  - **twMerge** (boolean) - Optional - Whether to enable Tailwind merge. Defaults to `true` in the default build.
  - **twMergeConfig** (object) - Optional - Configuration for Tailwind merge, e.g., `extend.classGroups`.

### Example
```ts
const button = tv(
  { base: 'px-2', variants: { size: { lg: 'px-4' } } },
  { twMerge: true, twMergeConfig: { /* ... */ } }
);
```
```

--------------------------------

### Use tv recipe in Vue

Source: https://www.tailwind-variants.org/docs/quick-start

Use the button recipe in a Vue template with :class binding.

```vue
<button :class="button({ color: 'primary' })">Save</button>
```

--------------------------------

### Use tv recipe in React

Source: https://www.tailwind-variants.org/docs/quick-start

Use the button recipe in a React component with className.

```tsx
<button className={button({ color: "primary" })}>Save</button>
```

--------------------------------

### Extend a slotted recipe and merge slots by key

Source: https://www.tailwind-variants.org/docs/extending

Demonstrates extending slotted recipes: `mediaCard` inherits `base` and `description` slots from `card`, adds a new `media` slot, and overrides the `title` slot style. The destructured call shows the resulting slot keys.

```ts
import { tv } from 'tailwind-variants';

const card = tv({
  slots: {
    base: 'rounded-xl border p-4',
    title: 'text-sm font-medium',
    description: 'text-sm text-zinc-500'
  }
});

const mediaCard = tv({
  extend: card,
  slots: {
    media: 'mb-3 aspect-video rounded-lg bg-zinc-100',
    title: 'text-base font-semibold'
  }
});

const { base, media, title, description } = mediaCard();
```

--------------------------------

### Apply compound slots with tv()

Source: https://www.tailwind-variants.org/docs/slots

Use `compoundSlots` to apply extra classes to specific slots when variant conditions match. Same idea as compound variants, but targeted per slot. Use when a combination should restyle only certain parts.

```ts
const card = tv({
  slots: { base: 'rounded-xl p-4', header: 'font-bold' },
  variants: {
    elevated: { true: {}, false: {} }
  },
  compoundSlots: [
    {
      elevated: true,
      slots: ['base'],
      class: 'shadow-lg'
    }
  ]
});
```

--------------------------------

### tv() usage and returned metadata

Source: https://www.tailwind-variants.org/docs/api-reference

Shows the call signature of tv() and the properties available on the returned recipe function. When slots are defined, calling the recipe returns an object with slot functions; otherwise it returns a string.

```ts
const button = tv(options, config?);

button({ variant: 'primary' }); // => string (no slots)
button({ variant: 'primary' }).base(); // => string (with slots)

button.base;              // resolved base string
button.slots;             // slot class map
button.variants;          // variant definitions
button.variantKeys;       // ['variant', 'size', ...]
button.defaultVariants;   // { variant: 'primary', ... }
button.compoundVariants;  // array
button.compoundSlots;     // array
```

--------------------------------

### Using slots: {} for slot mode

Source: https://www.tailwind-variants.org/docs/faq

Demonstrates that an explicit empty slots object enables slot mode with a single implicit base slot, while omitting slots returns a plain string.

```ts
const x = tv({ slots: {}, base: 'p-4' });
x().base(); // slot function

const y = tv({ base: 'p-4' });
y(); // plain string — omit slots entirely
```

--------------------------------

### cx

Source: https://www.tailwind-variants.org/docs/class-resolution

Joins class strings without resolving conflicts. Same role as `clsx` — smaller and faster when merge is unnecessary. Available on both default and lite builds.

```APIDOC
## `cx`

### Description
Joins class strings without resolving conflicts. Same role as `clsx` — smaller and faster when merge is unnecessary. Available on both default and lite builds.

### Import
```ts
import { cx } from 'tailwind-variants';
// or
import { cx } from 'tailwind-variants/lite';
```

### Parameters
- **inputs** (string | object | array) - Required - Class strings, objects, or arrays to concatenate.

### Returns
- **string** - The concatenated class string without conflict resolution.

### Example
```ts
cx('text-blue-500', 'text-red-500'); // => "text-blue-500 text-red-500"
cx(['px-4', 'py-2'], { hidden: false }); // => "px-4 py-2"
```
```

--------------------------------

### Chain extend to combine multiple base recipes

Source: https://www.tailwind-variants.org/docs/extending

Shows how to extend multiple recipes by manually chaining `extend` calls, since only one parent recipe is allowed per definition. The `final` recipe inherits from `extended`, which itself inherits from `baseButton`.

```ts
const extended = tv({ extend: baseButton });
const final = tv({ extend: extended /* ... */ });
```

--------------------------------

### list_pages

Source: https://www.tailwind-variants.org/docs/mcp-server

Lists all documentation pages with metadata.

```APIDOC
## list_pages

### Description
Lists all documentation pages with their title, description, HTML/Markdown URLs, and slugs.

### Method
MCP Tool

### Endpoint
https://www.tailwind-variants.org/api/mcp

### Parameters
No arguments required.

### Response
Returns a list of pages with title, description, HTML/Markdown URLs, and slugs.
```

--------------------------------

### Replace cnBase with cx in v3.2.0

Source: https://www.tailwind-variants.org/docs/migration

In v3.1.1 to v3.2.0, replace cnBase with cx. The diff shows the import and usage changes.

```diff
- import { cnBase } from 'tailwind-variants';
+ import { cx } from 'tailwind-variants';

- cnBase('flex gap-2', className);
+ cx('flex gap-2', className);
```

--------------------------------

### cx

Source: https://www.tailwind-variants.org/docs/api-reference

Lightweight concat without conflict resolution.

```APIDOC
## `cx`

### Description
Lightweight concat without conflict resolution.

### Signature
```ts
cx(...inputs)
```

### Parameters
- **inputs** (ClassValue[]) - Required - Class values to concatenate.

### Return Value
Returns a string with concatenated classes.

### Example
```ts
cx('text-blue-500', 'text-red-500'); // => "text-blue-500 text-red-500"
```

### Notes
Available in default and lite builds. Replaces deprecated `cnBase`.
```

--------------------------------

### Prettier configuration for tv

Source: https://www.tailwind-variants.org/docs/quick-start

If using prettier-plugin-tailwindcss, include tv in the tailwindFunctions list to keep class order consistent.

```js
// prettier.config.js
module.exports = {
  plugins: ["prettier-plugin-tailwindcss"],
  tailwindFunctions: ["tv", "cn", "cx"],
};
```

--------------------------------

### Responsive variant values with sm: prefixes in tv()

Source: https://www.tailwind-variants.org/docs/responsive

Bake responsive utilities into variant values. The size variant uses sm: prefixes so the primary action stays full-width until the sm breakpoint. The comment shows the expected behavior: full-width CTA becomes inline from sm.

```ts
import { tv } from 'tailwind-variants';

const button = tv({
  base: 'inline-flex cursor-pointer items-center justify-center rounded-lg font-medium select-none transition-colors',
  variants: {
    variant: {
      primary: 'bg-zinc-900 text-white',
      secondary: 'border border-zinc-300 bg-zinc-50 text-zinc-900',
      tertiary: 'text-zinc-700 hover:bg-zinc-200/70'
    },
    size: {
      sm: 'h-9 px-3 text-[0.8125rem] sm:px-3.5 sm:text-sm',
      lg: 'h-10 w-full px-4 text-sm sm:w-auto sm:min-w-36'
    }
  },
  defaultVariants: {
    variant: 'primary',
    size: 'sm'
  }
});

button({ size: 'lg' });
// full-width CTA → inline from sm
```

--------------------------------

### Request Markdown via content negotiation

Source: https://www.tailwind-variants.org/docs/llms-txt

Send this HTTP request to retrieve the Markdown version of a documentation page. The server returns the same body as the .md URL when the Accept header prefers text/markdown.

```http
GET /docs/variants HTTP/1.1
Accept: text/markdown
```

--------------------------------

### Badge recipe with compoundVariants for color combinations

Source: https://www.tailwind-variants.org/docs/recipes

Defines a badge component with variant (solid, soft, outline), color (default, primary, success, danger), and size (sm, md) variants. Uses compoundVariants to apply color-specific classes for each variant. Defaults to soft/default/sm. Exports the BadgeVariants type.

```ts
import { tv, type VariantProps } from 'tailwind-variants';

export const badge = tv({
  base: 'inline-flex select-none items-center rounded-full font-medium',
  variants: {
    variant: {
      solid: '',
      soft: '',
      outline: 'border bg-transparent'
    },
    color: {
      default: '',
      primary: '',
      success: '',
      danger: ''
    },
    size: {
      sm: 'px-2 py-0.5 text-xs',
      md: 'px-2.5 py-0.5 text-sm'
    }
  },
  compoundVariants: [
    { variant: 'solid', color: 'default', class: 'bg-zinc-900 text-white' },
    { variant: 'solid', color: 'primary', class: 'bg-blue-600 text-white' },
    { variant: 'solid', color: 'success', class: 'bg-green-600 text-white' },
    { variant: 'solid', color: 'danger', class: 'bg-red-600 text-white' },
    { variant: 'soft', color: 'default', class: 'bg-zinc-100 text-zinc-700' },
    { variant: 'soft', color: 'primary', class: 'bg-blue-100 text-blue-700' },
    { variant: 'outline', color: 'default', class: 'border-zinc-300 text-zinc-700' },
    { variant: 'outline', color: 'primary', class: 'border-blue-300 text-blue-700' }
  ],
  defaultVariants: {
    variant: 'soft',
    color: 'default',
    size: 'sm'
  }
});

export type BadgeVariants = VariantProps<typeof badge>;
```

--------------------------------

### Alert recipe with slots and color variants

Source: https://www.tailwind-variants.org/docs/recipes

Defines an alert component using slots (base, icon, content, title, description) and a color variant with default, success, warning, and danger options. Defaults to the 'default' color. Exports the AlertVariants type.

```ts
import { tv, type VariantProps } from 'tailwind-variants';

export const alert = tv({
  slots: {
    base: 'flex gap-3 rounded-lg p-4 border',
    icon: 'size-5 shrink-0 mt-0.5',
    content: 'flex-1 min-w-0',
    title: 'font-semibold leading-snug',
    description: 'text-sm mt-1 opacity-90'
  },
  variants: {
    color: {
      default: {
        base: 'bg-zinc-50 border-zinc-200 text-zinc-900',
        icon: 'text-zinc-500'
      },
      success: {
        base: 'bg-green-50 border-green-200 text-green-900',
        icon: 'text-green-600'
      },
      warning: {
        base: 'bg-amber-50 border-amber-200 text-amber-900',
        icon: 'text-amber-600'
      },
      danger: {
        base: 'bg-red-50 border-red-200 text-red-900',
        icon: 'text-red-600'
      }
    }
  },
  defaultVariants: {
    color: 'default'
  }
});

export type AlertVariants = VariantProps<typeof alert>;
```

--------------------------------

### Button recipe with variants and compoundVariants

Source: https://www.tailwind-variants.org/docs/recipes

Defines a button component with variants for visual style (primary, secondary, tertiary) and size (sm, md, lg). Includes compound variants for large primary and secondary buttons, and defaults to primary/md. Exports the ButtonVariants type for prop typing.

```ts
import { tv, type VariantProps } from 'tailwind-variants';

export const button = tv({
  base: [
    'inline-flex cursor-pointer items-center justify-center gap-2 select-none',
    'rounded-lg font-medium transition-colors',
    'disabled:cursor-not-allowed disabled:opacity-50'
  ],
  variants: {
    variant: {
      primary: 'bg-zinc-900 text-white hover:bg-zinc-800',
      secondary: 'border border-zinc-300 bg-zinc-50 text-zinc-900 hover:bg-zinc-100',
      tertiary: 'text-zinc-700 hover:bg-zinc-200/70 hover:text-zinc-950'
    },
    size: {
      sm: 'h-8 px-3 text-sm',
      md: 'h-10 px-4 text-sm',
      lg: 'h-12 px-6 text-base'
    }
  },
  compoundVariants: [
    { variant: 'primary', size: 'lg', class: 'shadow-lg shadow-zinc-900/15' },
    { variant: 'secondary', size: 'lg', class: 'shadow-sm' }
  ],
  defaultVariants: {
    variant: 'primary',
    size: 'md'
  }
});

export type ButtonVariants = VariantProps<typeof button>;
```

--------------------------------

### Combine multiple variant keys (variant, size)

Source: https://www.tailwind-variants.org/docs/variants

Defines a button recipe with two independent variant axes: `variant` and `size`. Call with `{ variant: 'primary', size: 'lg' }` to apply both. Each key is an independent axis.

```TypeScript
const button = tv({
  base: 'inline-flex cursor-pointer items-center justify-center rounded-full font-medium select-none transition-colors',
  variants: {
    variant: {
      primary: 'bg-zinc-900 text-white',
      secondary: 'border border-zinc-300 bg-zinc-50 text-zinc-900',
      tertiary: 'text-zinc-700'
    },
    size: {
      sm: 'h-8 px-3 text-sm',
      md: 'h-10 px-4 text-sm',
      lg: 'h-11 px-5 text-base'
    }
  }
});

button({ variant: 'primary', size: 'lg' });
```
Tokens:
Raw