---
title: "Core Concepts"
description: "Master the fundamental concepts that power shadcn/ui: primitives, variants, composition, and the design system approach that makes everything work together."
canonical_url: "https://vercel.com/academy/shadcn-ui/core-concepts"
md_url: "https://vercel.com/academy/shadcn-ui/core-concepts.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-04-11T07:44:41.422Z"
content_type: "lesson"
course: "shadcn-ui"
course_title: "React UI with shadcn/ui + Radix + Tailwind"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Core Concepts

Understanding shadcn/ui means understanding the core concepts that make it work. These aren't just technical details – they're the foundational ideas that enable the entire approach. Let's explore each concept and see how they work together to create such a powerful development experience.

If you'd like to learn more about the theory behind shadcn/ui and other modern component libraries, Vercel maintains the official spec at [components.build](https://components.build/).

## 1. Primitives: The Foundation Layer

At the heart of most shadcn/ui components is a [Radix UI primitive](https://www.radix-ui.com/primitives). These primitives provide the complex behavior (accessibility, keyboard navigation, focus management) while remaining completely unstyled.

Think of primitives as the "engine" of a component – they handle all the complex logic so you can focus on appearance and customization.

```tsx title="components/ui/dialog.tsx"
import * as DialogPrimitive from "@radix-ui/react-dialog"

// Raw primitive usage (unstyled)
<DialogPrimitive.Root>
  <DialogPrimitive.Trigger>Open</DialogPrimitive.Trigger>
  <DialogPrimitive.Portal>
    <DialogPrimitive.Overlay />
    <DialogPrimitive.Content>
      <DialogPrimitive.Title>Dialog Title</DialogPrimitive.Title>
      <DialogPrimitive.Description>Dialog content</DialogPrimitive.Description>
      <DialogPrimitive.Close>Close</DialogPrimitive.Close>
    </DialogPrimitive.Content>
  </DialogPrimitive.Portal>
</DialogPrimitive.Root>
```

This raw primitive provides all the functionality you need:

- Proper ARIA attributes for screen readers
- Keyboard navigation (ESC to close, Tab to cycle focus)
- Focus management (trapping focus within the dialog)
- Portal rendering (rendering outside the DOM hierarchy)
- Event handling (click outside to close)

But it has no visual styling at all. That's where shadcn/ui comes in.

### Why Primitives Matter

Primitives solve one of the hardest problems in UI development: making components accessible by default. Writing accessible components from scratch requires deep knowledge of ARIA specifications, keyboard interaction patterns, and focus management. Primitives give you all of this for free.

\*\*Note: Accessibility by Default\*\*

Every shadcn/ui component inherits the accessibility features of its underlying primitive. This means you get proper screen reader support, keyboard navigation, and focus management without having to think about it. You're building inclusive applications by default.

## 2. Variants: Systematic Styling

shadcn/ui uses a library called [class-variance-authority](https://cva.style/docs) (CVA) to create systematic, type-safe styling variants. This allows components to have multiple appearances while maintaining consistency.

```tsx title="components/ui/button.tsx"
import { cva, type VariantProps } from "class-variance-authority"

// Define variants systematically
const buttonVariants = cva(
  // Base classes that apply to all variants
  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      // Different visual styles
      variant: {
        default: "bg-primary text-primary-foreground shadow hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
        outline: "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      // Different sizes
      size: {
        default: "h-9 px-4 py-2",
        sm: "h-8 rounded-md px-3 text-xs",
        lg: "h-10 rounded-md px-8",
        icon: "h-9 w-9",
      },
    },
    // Default values
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

// Usage with full TypeScript support
<Button variant="destructive" size="lg">
  Delete Account
</Button>
```

This approach provides several benefits:

- **Type Safety**: TypeScript knows exactly which variants are available and prevents typos.
- **Consistency**: All variant definitions are in one place, making it easy to maintain design consistency.
- **Composability**: Variants can be combined (e.g., `variant="outline" size="sm"`).
- **Extensibility**: Adding new variants is as simple as adding them to the configuration.

## 3. Composition: Building Complex UIs

shadcn/ui components are designed to be composed together to create more complex interfaces. Rather than providing monolithic components, the library provides flexible building blocks.

Instead of a single `<DataTable>` component with many props, you compose smaller components together.

```tsx title="my-card.tsx"
<Card>
  <CardHeader>
    <CardTitle>Recent Orders</CardTitle>
    <CardDescription>
      You have 3 orders this month
    </CardDescription>
  </CardHeader>
  <CardContent>
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead>Order</TableHead>
          <TableHead>Status</TableHead>
          <TableHead>Amount</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        <TableRow>
          <TableCell>
            <div className="font-medium">Order #3210</div>
            <div className="text-sm text-muted-foreground">
              2 minutes ago
            </div>
          </TableCell>
          <TableCell>
            <Badge variant="outline">Processing</Badge>
          </TableCell>
          <TableCell>$42.25</TableCell>
        </TableRow>
      </TableBody>
    </Table>
  </CardContent>
</Card>
```

This compositional approach offers several advantages:

- **Flexibility**: You can mix and match components to create exactly the interface you need.
- **Reusability**: Individual components can be used in different contexts.
- **Maintainability**: Changes to individual components don't affect other compositions.
- **Learning**: Understanding smaller components makes it easier to understand larger patterns.

## 4. Design System Integration

shadcn/ui doesn't just provide components – it provides a complete design system approach using [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties) and [Tailwind CSS](https://tailwindcss.com/).

Your design system is defined using CSS custom properties that create semantic color tokens. This approach is crucial because it separates the visual design from the component logic, allowing you to maintain consistent theming across your entire application while enabling easy customization and dark mode support.

Semantic tokens like `--primary`, `--background`, and `--foreground` describe the purpose of colors rather than their appearance, making your design system more maintainable and accessible.

```css title="globals.css"
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --card: 0 0% 100%;
  --card-foreground: 222.2 84% 4.9%;
  --popover: 0 0% 100%;
  --popover-foreground: 222.2 84% 4.9%;
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96%;
  --secondary-foreground: 222.2 84% 4.9%;
  --muted: 210 40% 96%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96%;
  --accent-foreground: 222.2 84% 4.9%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 210 40% 98%;
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;
  --ring: 221.2 83.2% 53.3%;
  --radius: 0.5rem;
}
```

```yaml
quiz:
  question: "What is the primary purpose of Radix UI primitives in shadcn/ui components?"
  choices:
    - id: "styling"
      text: "To provide default styling and visual appearance"
    - id: "behavior"
      text: "To provide accessible behavior and complex logic"
    - id: "performance"
      text: "To optimize rendering performance and bundle size"
    - id: "typescript"
      text: "To provide TypeScript support and type safety"
  correctAnswerId: "behavior"
  feedback: "{\n    correct: 'Correct! Radix UI primitives provide all the complex behavior (accessibility, keyboard navigation, focus management) while remaining completely unstyled.',\n    incorrect: 'Radix UI primitives are specifically designed to be unstyled and focus purely on providing accessible behavior and complex interaction logic.'\n  }"
```

## 5. The `cn` Utility: Conditional Styling

One small but crucial concept is the `cn` utility function that enables conditional and composable styling:

```tsx
import { cn } from "@/lib/utils"

// The cn function combines class names intelligently
function Button({ className, variant, size, ...props }) {
  return (
    <button
      className={cn(
        buttonVariants({ variant, size }),
        className
      )}
      {...props}
    />
  )
}

// Usage allows for additional customization
<Button 
  variant="outline" 
  className="w-full border-dashed" // Additional classes
>
  Custom Button
</Button>
```

The `cn` function (typically using `clsx` and `tailwind-merge` under the hood) provides intelligent class name merging that handles conflicts and conditional styling.

## 6. The `asChild` Pattern: Maximum Flexibility

Many shadcn/ui components support an `asChild` prop that allows you to change the rendered element. This is useful when you want to use a component as a child of another component.

```tsx title="my-button.tsx"
import { Slot } from "@radix-ui/react-slot"

// Normal usage renders a button element
<Button>Click me</Button>

// asChild renders the child element with Button styling
<Button asChild>
  <Link href="/dashboard">Go to Dashboard</Link>
</Button>
```

This pattern provides maximum flexibility while maintaining consistent styling and behavior.

\*\*Reflection:\*\* Think about how these concepts work together. How do primitives, variants, and composition combine to create flexible yet consistent components? Can you imagine building a component that uses all of these patterns?

## How It All Works Together

These concepts combine to create a powerful system:

1. **Primitives** provide robust, accessible behavior
2. **Variants** create systematic, type-safe styling options
3. **Composition** allows building complex UIs from simple components
4. **Design system integration** ensures consistency across your application
5. **Utility functions** enable flexible customization
6. **React best practices** ensure components work well with the broader ecosystem

The result is a component system that's both powerful and approachable, giving you the benefits of a mature design system while maintaining complete control over your code.

## Understanding the Mental Model

When working with shadcn/ui, think of components as:

- **Behavior** (from Radix primitives)
- **Appearance** (from Tailwind classes and variants)
- **Composition** (how components fit together)
- **Customization** (your additions and modifications)

This mental model helps you understand how to use, modify, and extend components effectively.

## What's Next

Now that you understand the core concepts, you're ready to see how they're configured and coordinated in practice. In our next lesson, we'll explore the `components.json` file – the central configuration that ties all of these concepts together and makes the shadcn/ui CLI work its magic.


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)