Using class-recipe with shadcn/ui
shadcn/ui copies components into your project.
They style their variants with class-variance-authority and merge classes
with a cn helper. class-recipe replaces both, and the components keep
their imports and their API.
Keep cn in lib/utils.ts
Section titled “Keep cn in lib/utils.ts”shadcn/ui components import cn from @/lib/utils. Create cn, cva,
and sva there, with twMerge as the join, so that a className passed
to a component replaces the classes it conflicts with, as before:
import { createRecipes } from "@lynstack/class-recipe";import { twMerge } from "tailwind-merge";
export const { cx: cn, cva, sva } = createRecipes({ join: twMerge });The cx that createRecipes returns joins its inputs as clsx does,
then merges them, as the cn of shadcn/ui does. So every component that
imports cn keeps working, and you can remove clsx from your
dependencies once nothing else imports it.
With the cn package, pass it as the
join under another name, since this module exports its own cn:
import { createRecipes } from "@lynstack/class-recipe";import { cn as merge } from "cn";
export const { cx: cn, cva, sva } = createRecipes({ join: merge });See Merging classes for which one fits your version of Tailwind CSS.
Convert a component
Section titled “Convert a component”npx shadcn add generates components that import cva and
VariantProps from class-variance-authority. For each component:
- Import
cvafrom@/lib/utilsinstead. - Turn
cva(base, config)intocva({ base, ...config }). - Replace
VariantPropswithVariantsOf, from@lynstack/class-recipe. - Pass
classNameto the recipe, and drop thecncall around it. The recipe addsclassNamelast, and merges it with its join.
Here is a button.tsx built on Base UI before the
change. The exact classes depend on your version of shadcn/ui:
import { Button as ButtonPrimitive } from "@base-ui/react/button";import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";
const buttonVariants = cva( "inline-flex shrink-0 items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-all outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", { variants: { variant: { default: "bg-primary text-primary-foreground hover:bg-primary/90", destructive: "bg-destructive text-white hover:bg-destructive/90", outline: "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground", secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80", ghost: "hover:bg-accent hover:text-accent-foreground", link: "text-primary underline-offset-4 hover:underline", }, size: { default: "h-9 px-4 py-2 has-[>svg]:px-3", sm: "h-8 gap-1.5 rounded-md px-3 has-[>svg]:px-2.5", lg: "h-10 rounded-md px-6 has-[>svg]:px-4", icon: "size-9", }, }, defaultVariants: { variant: "default", size: "default", }, },);
function Button({ className, variant = "default", size = "default", ...props}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>) { return ( <ButtonPrimitive data-slot="button" className={cn(buttonVariants({ variant, size, className }))} {...props} /> );}
export { Button, buttonVariants };And after:
import { Button as ButtonPrimitive } from "@base-ui/react/button";import type { VariantsOf } from "@lynstack/class-recipe";import { cva } from "@/lib/utils";
const buttonVariants = cva({ base: "inline-flex shrink-0 items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-all outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", variants: { variant: { default: "bg-primary text-primary-foreground hover:bg-primary/90", destructive: "bg-destructive text-white hover:bg-destructive/90", outline: "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground", secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80", ghost: "hover:bg-accent hover:text-accent-foreground", link: "text-primary underline-offset-4 hover:underline", }, size: { default: "h-9 px-4 py-2 has-[>svg]:px-3", sm: "h-8 gap-1.5 rounded-md px-3 has-[>svg]:px-2.5", lg: "h-10 rounded-md px-6 has-[>svg]:px-4", icon: "size-9", }, }, defaultVariants: { variant: "default", size: "default", },});
function Button({ className, variant = "default", size = "default", ...props}: ButtonPrimitive.Props & VariantsOf<typeof buttonVariants>) { return ( <ButtonPrimitive data-slot="button" className={(state) => buttonVariants({ variant, size, className: typeof className === "function" ? className(state) : className, }) } {...props} /> );}
export { Button, buttonVariants };A Base UI component takes a className that is a string or a function
of its state, such as
className={(state) => (state.disabled ? "opacity-25" : "")}. A recipe
takes a string, so the component passes Base UI a function that resolves
className for the current state and calls the recipe with it.
class-variance-authority ignores a function className, which drops the
classes it returns; the recipe keeps them.
The component keeps its API: variant, size, the render prop of
Base UI, such as <Button nativeButton={false} render={<a href="/" />}>,
and the buttonVariants export, which other components and links call,
such as <a className={buttonVariants({ variant: "ghost" })}>.
A component built on Radix takes asChild and renders Slot instead,
and its className is a string: pass it to the recipe directly, as in
className={buttonVariants({ variant, size, className })}.
Every variant of the button has a default, so its props stay optional. In
a component whose variant has no default, VariantsOf makes that variant
required, where VariantProps left it optional. Give it a default, or
pass it at every call (see
Migrating from class-variance-authority).
Components with several elements
Section titled “Components with several elements”shadcn/ui marks each element of a component with a data-slot attribute,
such as data-slot="card-header". A component whose elements share
variants can use one slot recipe for all of them, with sva from
@/lib/utils. Name its slots after those elements, and keep the
data-slot attributes, which your CSS and tests may select (see
sva).
When you add more components
Section titled “When you add more components”npx shadcn add keeps generating imports from class-variance-authority.
Convert each new component as above. Until you do, it keeps working with
class-variance-authority, since the two libraries can live side by side.
Next steps
Section titled “Next steps”- Migrating from class-variance-authority lists the behaviors that change, and a test that checks a migrated recipe.
- Building components shows more component patterns.
- Merging classes explains what the join costs.