cn

PreviousNext

API reference for @udecode/cn.

@udecode/cn provides class-name helpers and component wrappers for React UI primitives. The package also re-exports @udecode/react-utils from its root entry.

Install

pnpm add @udecode/cn
pnpm add @udecode/cn

Quick Use

import * as React from 'react';
 
import { cn, withCn, withProps, withVariants } from '@udecode/cn';
 
const active = true;
const className = cn('px-2', active && 'bg-accent', 'px-4');
 
const ButtonBase = React.forwardRef<
  HTMLButtonElement,
  React.ComponentProps<'button'>
>((props, ref) => <button ref={ref} {...props} />);
 
const Button = withCn(ButtonBase, 'inline-flex items-center rounded-md');
 
const PrimaryButton = withProps(Button, {
  type: 'button',
  className: 'bg-primary text-primary-foreground',
});
import * as React from 'react';
 
import { cn, withCn, withProps, withVariants } from '@udecode/cn';
 
const active = true;
const className = cn('px-2', active && 'bg-accent', 'px-4');
 
const ButtonBase = React.forwardRef<
  HTMLButtonElement,
  React.ComponentProps<'button'>
>((props, ref) => <button ref={ref} {...props} />);
 
const Button = withCn(ButtonBase, 'inline-flex items-center rounded-md');
 
const PrimaryButton = withProps(Button, {
  type: 'button',
  className: 'bg-primary text-primary-foreground',
});

Ownership

SurfaceOwnerWhat It Does
cn@udecode/cnCombines class-variance-authority cx with tailwind-merge.
withCn@udecode/cnCreates a component with a default merged className.
withProps@udecode/cnCreates a forwardRef component with default props.
withVariants@udecode/cnCreates a forwardRef component that computes classes from cva variants.
React utility exports@udecode/react-utilsRe-exported from the @udecode/cn root entry.

Behavior

HelperBehavior
cn(...inputs)Runs values through cx, then resolves Tailwind conflicts with twMerge.
withCn(Component, ...inputs)Calls withProps with a default className created from cn.
withProps(Component, defaultProps)Merges default props first and consumer props second.
withProps class namesMerges defaultProps.className and props.className with cn.
withProps refsReturns React.forwardRef.
withVariants(Component, variants, onlyVariantsProps?)Applies variants(variantProps) and merges the result with className.
onlyVariantsPropsRemoves variant-only props from the rendered component props.

API Reference

cn

Merge conditional class values and resolve Tailwind conflicts.

cn('px-2', active && 'bg-accent', 'px-4');
cn('px-2', active && 'bg-accent', 'px-4');

Parameters

    Values accepted by class-variance-authority cx.

Returnsstring

    The merged class name.

withCn

Create a component with default classes.

const Card = withCn('div', 'rounded-md border bg-card');
const Card = withCn('div', 'rounded-md border bg-card');

Parameters

    Component receiving the default class name.

    Default class values.

ReturnsReact.ForwardRefExoticComponent

    A component that merges the default class name with consumer className.

withProps

Create a component with default props. Consumer props override default props, except class names are merged.

const SubmitButton = withProps('button', {
  type: 'submit',
  className: 'font-medium',
});
const SubmitButton = withProps('button', {
  type: 'submit',
  className: 'font-medium',
});

Parameters

    Component receiving default props.

    Props applied before consumer props.

ReturnsReact.ForwardRefExoticComponent

    A forwardRef component with merged class names.

withVariants

Create a component backed by class-variance-authority variants.

import { cva } from 'class-variance-authority';
 
const buttonVariants = cva('inline-flex items-center', {
  variants: {
    size: {
      sm: 'h-8 px-2',
      md: 'h-9 px-3',
    },
  },
});
 
const Button = withVariants('button', buttonVariants, ['size']);
import { cva } from 'class-variance-authority';
 
const buttonVariants = cva('inline-flex items-center', {
  variants: {
    size: {
      sm: 'h-8 px-2',
      md: 'h-9 px-3',
    },
  },
});
 
const Button = withVariants('button', buttonVariants, ['size']);

Parameters

    Component receiving variant classes.

    cva variant function.

    Variant props to remove before rendering the component.

ReturnsReact.ForwardRefExoticComponent

    A forwardRef component with variant props and merged class names.