shadcn

shadcn Best Practices

This document outlines our team's definitive best practices for developing with shadcn/ui. Adhere to these guidelines for all shadcn component development and integration.

1. Code Organization and Structure

Organize components logically to reflect UI hierarchy and promote discoverability.

Rule: Place domain-specific components under components/<domain> and reusable UI primitives under components/ui. Each component must reside in its own PascalCase file.

❌ BAD:

// components/Button.tsx
// components/profile-card.tsx
// components/user-settings/index.tsx (contains multiple components)

✅ GOOD:

// components/ui/Button.tsx
// components/forms/DatePicker.tsx
// components/layout/Sidebar.tsx

// components/forms/index.ts
export * from "./DatePicker";
export * from "./Input";

2. Component Architecture

Favor functional components, composition, and explicit prop definitions.

Rule: Use functional components with React.forwardRef and asChild for seamless integration with Radix primitives.

❌ BAD:

// No ref forwarding, no asChild
const Button = ({ children, onClick }) => (
  <button onClick={onClick}>{children}</button>
);

✅ GOOD:

// components/ui/Button.tsx
import * as React from "react";
import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils"; // Assuming you have a cn utility

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
);

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean;
}

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, asChild = false, ...props }, ref) => {
    const Comp = asChild ? Slot : "button";
    return (
      <Comp
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    );
  }
);
Button.displayName = "Button";

export { Button, buttonVariants };