Installation

One command. Zero config. Start building in seconds.

Magic Installation

Recommended

Everything you need in one command

Bash
# 🪄 Magic Installation - Everything in one command
ng add @ng-cn/core --theme=github --components=all

# Or with different themes
ng add @ng-cn/core --theme=vercel --components=all
ng add @ng-cn/core --theme=apple --components=all

This single command:

Installs all 56+ UI components
Configures Tailwind CSS v4 with PostCSS
Sets up beautiful theme presets
Creates utility functions (cn, animations)
Configures TypeScript path aliases
Adds accessibility utilities
Sets up dark mode support
Zero manual configuration needed

Quick Start

Set up core utilities, add components as needed

Bash
# Basic setup without components
ng add @ng-cn/core

# Or with a specific theme
ng add @ng-cn/core --theme=linear

Then add components individually with ng g @ng-cn/core:c <name>

Available Themes

Choose your design language

shadcn

Default clean, minimal design

--theme=shadcn
GitHub

Developer-focused aesthetic

--theme=github
Vercel

Bold black and white

--theme=vercel
Apple

Elegant, sophisticated

--theme=apple
OpenAI

Modern tech-forward

--theme=openai
ClickUp

Vibrant, colorful

--theme=clickup
Linear

Sleek, minimal

--theme=linear
Bash
# Available theme options
ng add @ng-cn/core --theme=shadcn     # Default minimal theme
ng add @ng-cn/core --theme=github     # GitHub's design language
ng add @ng-cn/core --theme=vercel     # Bold black & white
ng add @ng-cn/core --theme=apple      # Elegant Apple style
ng add @ng-cn/core --theme=openai     # Modern tech aesthetic
ng add @ng-cn/core --theme=clickup    # Vibrant colors
ng add @ng-cn/core --theme=linear     # Sleek minimal

What's in the Box

Everything included with the magic install

56+
Components
7
Theme Presets
∞
Customizable

Dependencies Installed

tailwindcss^4.1.18
@tailwindcss/postcss^4.1.18
@angular/cdk^21.0.5
lucide-angular^0.562.0
class-variance-authority^0.7.1
clsx^2.1.1
tailwind-merge^3.4.0

Utility Functions

cn()

Tailwind CSS class merging utility with conflict resolution

Animation utilities

Smooth transitions with AnimatedDirective, PresenceComponent

Accessibility utilities

FocusTrap, KeyboardNavigation, LiveRegion directives

Positioning utilities

Smart overlay positioning for popovers & dropdowns

Project Structure

Files added to your project

Plaintext
your-project/
├── postcss.config.mjs              # Tailwind CSS v4 PostCSS config
├── tsconfig.json                   # Updated with path aliases
├── src/
│   ├── ng-cn.scss                  # Theme CSS variables & base styles
│   ├── styles.scss                 # Auto-imports ng-cn.scss
│   └── app/
│       └── lib/
│           ├── utils/
│           │   ├── cn.ts                    # Class merging utility
│           │   ├── index.ts                 # Utils barrel export
│           │   ├── animation/               # Animation utilities
│           │   │   ├── animated.directive.ts
│           │   │   ├── presence.component.ts
│           │   │   └── animation-tokens.service.ts
│           │   ├── accessibility/           # A11y utilities
│           │   │   ├── focus-trap.directive.ts
│           │   │   ├── keyboard-navigation.directive.ts
│           │   │   ├── live-region.directive.ts
│           │   │   └── visually-hidden.component.ts
│           │   └── positioning/             # Overlay positioning
│           └── components/
│               └── ui/                      # Your components
│                   ├── button/
│                   ├── card/
│                   ├── dialog/
│                   └── ... (56+ with --components=all)
ng-cn.scss

Theme CSS variables with light/dark mode support, base styles, and animation keyframes

postcss.config.mjs

PostCSS configuration for Tailwind CSS v4

lib/utils/cn.ts

Class merging utility combining clsx and tailwind-merge

lib/utils/animation/

Animation utilities including AnimatedDirective and PresenceComponent

lib/utils/accessibility/

A11y utilities: FocusTrap, KeyboardNavigation, LiveRegion, VisuallyHidden

lib/utils/positioning/

Smart overlay positioning for popovers, tooltips, and dropdowns

lib/components/ui/

All UI components when using --components=all

Add Components

Install components one at a time

Bash
# Add individual components
ng g @ng-cn/core:c button
ng g @ng-cn/core:c card
ng g @ng-cn/core:c dialog

# Short alias
ng g @ng-cn/core:c input
ng g @ng-cn/core:c select
ng g @ng-cn/core:c tabs

Popular components:

buttoncarddialoginputselectcheckboxtabstabletoastdropdown-menuformsidebarcommandcalendarand 40+ more...

All Available Components

56+ components included with --components=all

Form Controls

buttoncheckboxinputinput-otplabelradio-groupselectsliderswitchtextareatoggletoggle-groupform

Data Display

avatarbadgecalendarcardcarouselchartprogressskeletontabledata-table

Feedback

alertalert-dialogdialogdrawersheettoasttooltipspinner

Navigation

breadcrumbcommanddropdown-menucontext-menumenubarnavigation-menupaginationsidebartabs

Layout

accordionaspect-ratiocollapsibleresizablescroll-areaseparator

Overlay

popoverhover-cardcomboboxdate-picker

Manual Setup

For those who prefer full control

1

Install dependencies

Bash
npm install clsx tailwind-merge class-variance-authority @angular/cdk lucide-angular tailwindcss @tailwindcss/postcss
2

Create PostCSS config for Tailwind v4

Create postcss.config.mjs:

Javascript
/** @type {import('postcss').Config} */
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};
3

Create the cn utility

Create src/app/lib/utils/cn.ts:

Typescript
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

/**
 * Merge Tailwind classes with proper conflict resolution.
 * @example cn('px-4 py-2', 'px-6') // => 'py-2 px-6'
 */
export function cn(...inputs: ClassValue[]): string {
  return twMerge(clsx(inputs));
}
4

Add CSS variables

Create src/ng-cn.scss and import in your styles:

Scss
@use "tailwindcss";

@custom-variant dark (&:is(.dark *));

:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --border: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  /* ... more variables */
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  /* ... dark mode overrides */
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  /* ... theme mappings */
}

@layer base {
  * { @apply border-border outline-ring/50; }
  body { @apply bg-background text-foreground; }
}
5

Configure path aliases

Add to tsconfig.json:

Json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@/lib/*": ["src/app/lib/*"],
      "@/ui/*": ["src/app/lib/components/ui/*"],
      "@/utils/*": ["src/app/lib/utils/*"]
    }
  }
}

You're ready!

Start building beautiful, accessible UIs with shadcn-angular.