V1.1

cn

Utilities for combining classNames with or without custom tailwind configurations to manage style conflicts.

clsxtailwind-merge

Installation

Install the following dependencies:

terminal
npm install clsx tailwind-merge@^2

Create a utils/cn.ts file and paste the following code into it.

/utils/cn.ts
import { borderRadii, shadows, texts } from '@/tailwind.config';
import clsx, { type ClassValue } from 'clsx';
import { extendTailwindMerge } from 'tailwind-merge';
 
export { type ClassValue } from 'clsx';
 
export const twMergeConfig = {
  extend: {
    classGroups: {
      'font-size': [
        {
          text: Object.keys(texts),
        },
      ],
      shadow: [
        {
          shadow: Object.keys(shadows),
        },
      ],
      rounded: [
        {
          rounded: Object.keys(borderRadii),
        },
      ],
    },
  },
};
 
const customTwMerge = extendTailwindMerge(twMergeConfig);
 
/**
 * Utilizes `clsx` with `tailwind-merge`, use in cases of possible class conflicts.
 */
export function cn(...classes: ClassValue[]) {
  return customTwMerge(clsx(...classes));
}

IntelliSense setup (optional)

If you are using VSCode and the TailwindCSS IntelliSense Extension, you have to add the following to your .vscode/settings.json file to enable Intellisense features for cn and tv functions.

.vscode/settings.json
"tailwindCSS.experimental.classRegex": [
  ["([\"'`][^\"'`]*.*?[\"'`])", "[\"'`]([^\"'`]*).*?[\"'`]"]
]

Prettier setup (optional)

If you're using prettier-plugin-tailwindcss, you can include cn in the functions list to ensure it gets sorted as well.

prettier.config.mjs
const config = {
  // ...
  plugins: ['prettier-plugin-tailwindcss'],
  tailwindFunctions: ['cn'],
};
 
export default config;

Examples

cn

In this example, cn is used to merge Tailwind classes and conditionally apply styles based on the isActive prop while managing potential class conflicts.

/examples/cn-ext.ts
import { cn } from '@/utils/cn';
 
function MyComponent({
  className,
  isActive,
  ...rest
}: React.HTMLAttributes<HTMLDivElement> & {
  isActive?: boolean;
}) {
  return (
    <div
      className={cn(
        'text-text-strong-950 bg-bg-white-0 size-3',
        {
          'text-text-white-0 bg-bg-strong-950': isActive,
        },
        className,
      )}
      {...rest}
    />
  );
}
© 2024 AlignUI Design System. All rights reserved.