Type hinting and annotation for tailwind classes in react (jsx,tsx)

[arunkumar413]

Hi Team,

I'm thinking of an idea where tailwind classes related to a component pattern appearing frequently are grouped together in an array as below. This keeps the HTML less polluted in a react component. I would like to know if there is a way to type annotate the array with an enum so that only valid tailwind classes are allowed.

const primaryBtnClasses = ["text-lg", 'bg-blue-500', "px-5", "py-3", "text-white"]

<button className={primaryBtnClasses.join(" ")}> Click me </button>

Thanks,
Arun

[kaileyventures]

tailwind doesn't ship a type for that, there's no enum of all the classes to import. there can't really be one either, arbitrary values make the list endless.

you'd just type the array yourself:

type BtnClass = "text-lg" | "bg-blue-500" | "px-5" | "py-3" | "text-white"
const primaryBtnClasses: BtnClass[] = ["text-lg", "bg-blue-500", "px-5", "py-3", "text-white"]

typescript rejects anything not in the union, so a typo fails at compile time. the official tailwind css intellisense extension also flags classes that don't exist while you type, which catches most typos before you even get there.

[TbhVishal]

Hi @arunkumar413!

Because Tailwind CSS allows arbitrary values (w-[123px], bg-[#123456]), TypeScript cannot provide a global enum of all possible class combinations out of the box.

However, in production React codebases, here are the two standard patterns to get strong type-hinting, autocompletion, and deduplication for grouped Tailwind classes:

---

Method 1: Class Variance Authority (cva) (Industry Standard)

Used by shadcn/ui and modern design systems. cva creates strongly typed, reusable component class variants with full autocompletion:

import { cva, type VariantProps } from 'class-variance-authority';

const buttonVariants = cva(
  // Base classes that always apply
  'inline-flex items-center justify-center font-medium transition-colors focus:outline-none',
  {
    variants: {
      variant: {
        primary: 'bg-blue-600 text-white hover:bg-blue-700 px-5 py-3 rounded-lg',
        secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200 px-4 py-2 rounded-md',
      },
      size: {
        sm: 'text-sm',
        lg: 'text-lg',
      },
    },
    defaultVariants: {
      variant: 'primary',
      size: 'lg',
    },
  }
);

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {}

export function Button({ variant, size, className, ...props }: ButtonProps) {
  return <button className={buttonVariants({ variant, size, className })} {...props} />;
}

---

Method 2: Typed Helper with the Tailwind IntelliSense Extension

If you just want a clean array/tuple without extra dependencies, you can define a typed helper function.

To make the official Tailwind CSS IntelliSense extension in VS Code autocomplete inside your custom helper, add this to your .vscode/settings.json:

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

Then define your helper:

// Identity helper enabling IDE autocompletion regex
export const tw = (...classes: string[]) => classes.filter(Boolean).join(' ');

const primaryBtnClasses = tw(
  'text-lg',
  'bg-blue-500',
  'px-5',
  'py-3',
  'text-white'
);

<button className={primaryBtnClasses}>Click me</button>

This keeps your JSX clean and readable while preserving autocomplete and linting!

[fathiranugrahh]

Tailwind classes are plain strings, so TypeScript can't type-check them out of the box, there's no built-in typed className in Tailwind or React. What you can do:

1. Autocomplete + hover docs + diagnostics: install the official Tailwind CSS IntelliSense VS Code extension (https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss). It works in TSX files and gives you class completion, hover previews, and warnings for unknown classes.
2. Make IntelliSense understand helper functions: if you build class strings with cn(), cva() or tv(), the extension won't see them by default. Add the tailwindCSS.experimental.classRegex setting in VS Code so it treats those function arguments as class strings.
3. Real compile-time type safety: use tailwind-variants (https://www.tailwind-variants.org/) or cva with typed variant props, so invalid variants are a type error. If you want the class names themselves typed, codegen tools like tailwindcss-classnames generate a union type of all valid classes from your config, but that's extra maintenance and not official.

In practice, (1) + (2) is what most React + Tailwind teams use; full type-checking of every class string is usually more trouble than it's worth.

[lak-is-law]

Hi @arunkumar413!

There are two main reasons generating a strict TypeScript enum/union for all possible Tailwind CSS classes isn't standard practice:

Dynamic / Arbitrary classes: Tailwind utilities support arbitrary values (like bg-[#1da1f2], w-[320px], grid-cols-[1fr_auto]), making the full set of valid classes mathematically infinite.
TypeScript Compiler Performance: Creating a union of tens of thousands of utility strings can cause significant IDE lag and trigger TypeScript's "Type instantiation is excessively deep and possibly infinite" error.

That said, here are the two industry-standard patterns used across the React ecosystem to solve this cleanly:

1. The Recommended Standard: Class Variance Authority (cva)

Instead of raw string arrays, use cva
(which powers component libraries like shadcn/ui). It keeps your JSX completely clean, handles component variants, and gives full TypeScript type inference:

tsx
import { cva, type VariantProps } from 'class-variance-authority';
const buttonVariants = cva(
// Base classes applied to all buttons
'inline-flex items-center justify-center font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 px-5 py-3 text-lg',
{
variants: {
variant: {
primary: 'bg-blue-500 text-white hover:bg-blue-600',
secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
},
},
defaultVariants: {
variant: 'primary',
},
}
);

2. If you want string arrays with IDE Autocomplete & Validation

If you prefer keeping string arrays or helper functions, configure the Tailwind CSS IntelliSense extension in VS Code to autocomplete and lint classes inside custom functions or arrays.

Add this to .vscode/settings.json:

json
{
"tailwindCSS.experimental.classRegex": [
["(?:clsx|cn|classNames|tw)\(([^)])\)", "["']([^\"']).?"']"], ["([a-zA-Z0-9_-]+Classes)\\s*=\\s*\\[([^\\]]*)\\]", "[\"'.?["'`]"]
]
}

Now, any array named *Classes (like primaryBtnClasses) will automatically get Tailwind autocomplete, linting, and error squiggles directly in your editor.

Pair this with clsx and tailwind-merge to merge arrays cleanly:

tsx
import clsx from 'clsx';
import { twMerge } from 'tailwind-merge';
export const cn = (...inputs: any[]) => twMerge(clsx(inputs));
const primaryBtnClasses = ['text-lg', 'bg-blue-500', 'px-5', 'py-3', 'text-white'];
Click me
interface ButtonProps
extends React.ButtonHTMLAttributes,
VariantProps {}
export function Button({ variant, className, children, ...props }: ButtonProps) {
return (
<button className={buttonVariants({ variant, className })} {...props}>
{children}

);
}

If it helped, kindly mark it as answered
Regards,
Lakshya

[Rukshan2000]

Written for: Arun and the team.

---

Hi Arun,

Short answer: there's no practical type or enum that covers every valid Tailwind class. The set is effectively unlimited: variants (hover:, md:, dark:), arbitrary values (w-[37px]), opacity modifiers (bg-blue-500/50), and anything added in your own config. Tailwind doesn't ship such a type. Generated union types do exist, but they get huge, slow down the TypeScript compiler, and fall behind your config.

Here's what works instead.

1. Lint the classes instead of typing them (recommended). eslint-plugin-tailwindcss has a no-custom-classname rule that flags any class Tailwind doesn't know, and it reads your config. Add your variable naming pattern to its callee and tag settings so it checks your arrays too.

2. Get autocomplete inside the array. The Tailwind CSS IntelliSense VS Code extension can autocomplete and flag classes outside className if you set tailwindCSS.experimental.classRegex to match your arrays. Older versions of the extension may need the setting below; current ones use tailwindCSS.classFunctions (e.g. ["cva", "clsx"]) instead.

"tailwindCSS.experimental.classRegex": [
  ["Classes\\s*=\\s*\\[([^\\]]*)\\]", "[\"'`]([^\"'`]*)[\"'`]"]
]

3. If you want a type anyway, keep it to a small allow-list.

type Size = "sm" | "lg" | "xl";
type Color = "blue" | "red" | "gray";
type Shade = 100 | 500 | 700;
type TwClass = `text-${Size}` | `bg-${Color}-${Shade}` | `px-${number}` | `py-${number}` | "text-white";

const primaryBtnClasses: TwClass[] = ["text-lg", "bg-blue-500", "px-5", "py-3", "text-white"];

Each class family you add has to be maintained by hand. Typos are caught, but anything you haven't listed is rejected even when it's a valid Tailwind class.

4. For the grouping itself, a plain string is enough, since .join(" ") adds nothing:

const primaryBtn = "text-lg bg-blue-500 px-5 py-3 text-white";

For buttons with variants (primary, secondary, sizes), class-variance-authority (cva) or tailwind-variants handle this pattern, and the IntelliSense extension supports both. If you'd rather keep the markup clean, you can also move the group into CSS with @apply (.btn-primary { @apply text-lg bg-blue-500 ... }).

My suggestion: use a string or cva, plus the ESLint rule and IntelliSense. You get the validation you're after without maintaining a type.

Thanks,