ply

> **MIT free-tier source.** Components live in `components/` (same layout as `npx ply-ui-cli add`). CLI and MCP live in `packages/`. Pro items are not stored here — install those with `PLY_LICENSE_KEY` from [ply-ui.com](https://ply-ui.com).
>
> **Angular 19+:** free components on [`compat/angular-19`](https://github.com/ply-ui-ng/ply/tree/compat/angular-19). `main` is Angular 22 (signal-forms `[formField]`).

# Ply — Angular + Tailwind Component Library

[![npm](https://img.shields.io/npm/v/ply-ui-cli.svg)](https://www.npmjs.com/package/ply-ui-cli)
[![npm downloads](https://img.shields.io/npm/dw/ply-ui-cli.svg)](https://www.npmjs.com/package/ply-ui-cli)
[![GitHub stars](https://img.shields.io/github/stars/ply-ui-ng/ply?style=social)](https://github.com/ply-ui-ng/ply)

**Ply** (formerly Base UI (Angular)) — [ply-ui.com](https://ply-ui.com) — is a CLI-first Angular + Tailwind CSS component library: **218 components and blocks** (128 free, 90 Pro), **390 icons**, and 18 full page layouts — standalone, zoneless, signal-based and **SSR-safe**, delivered shadcn-style: `npx ply-ui-cli add` copies the source into your project and it's yours. Not [MUI Base UI](https://base-ui.com) (React).

📚 **Documentation & live previews**: [ply-ui.com](https://ply-ui.com)  
📝 **Changelog**: [ply-ui.com/changelog](https://ply-ui.com/changelog) · [CHANGELOG.md](CHANGELOG.md) · [Issues](https://github.com/ply-ui-ng/ply/issues) · [Discussions](https://github.com/ply-ui-ng/ply/discussions)  
♿ **Accessibility (ACR)**: [ply-ui.com/accessibility](https://ply-ui.com/accessibility) · `npm run test:a11y`  
🖥️ **SSR-safe**: the docs site prerenders every catalog route, enforced by a blocking CI job · [how we verify it](https://ply-ui.com/learn/angular-ssr-safe-component-library/)  
🤖 **AI agents (MCP)**: [ply-ui.com/getting-started#ai-agents-mcp](https://ply-ui.com/getting-started#ai-agents-mcp) · `ply-ui-mcp` · [why copy-in UI works better with LLMs](https://ply-ui.com/learn/why-llms-write-better-code-with-copy-in-ui/) · [token walkthrough: rich text editor](https://ply-ui.com/learn/ai-agent-tokens-rich-text-editor/)  
🎨 **Figma Design System**: [Ply Design System](https://www.figma.com/design/hsUvEI3YXLCqrlwo6ENY4f/Ply-Design-System)  
✨ **See what you can build for free**: [Live Admin Dashboard Demo](https://demo.ply-ui.com/app/dashboard) (Source code: [ply-free-dashboard](https://github.com/ply-ui-ng/ply-free-dashboard))

---

## 🚀 Quick Start (Free Tier)

The free tier is production-ready with no account or license: **all primitives** (buttons, cards, dialogs, hover cards, menubars, inputs, currency fields, selects, tabs, stacked toasts, tooltips, and more) plus **all 19 form blocks** (login, signup, checkout, billing, wizard, …).

### 1. Initialize your project

```bash
npx ply-ui-cli init
```

This writes `ply-ui.json`, creates `ply-ui.css` (CDK overlay styles, keyframes, autofill fixes) imported from your global stylesheet, and downloads the icon sprites into your assets folder. Use `--yes` to accept defaults non-interactively. It does not install npm packages, so add the Angular CDK yourself: `npm install @angular/cdk`.

### 2. Configure Tailwind CSS

Ply works with **standard Tailwind CSS 4** — no custom theme file required.

1. Install Tailwind CSS 4 and PostCSS ([Angular guide](https://tailwindcss.com/docs/installation/framework-guides/angular)).
2. Create `src/tailwind.css`, register it in `angular.json` **before** global SCSS, and point `@source` at your templates. `@source` paths are relative to the CSS file:

```css
@import "tailwindcss";

@source "./**/*.{html,ts}";
```

Buttons, inputs, folder/underline/pills tabs, selects, combobox, toast, accordion, and the command palette read `--ply-primary` from `ply-ui.css`. That file aliases `--color-blue-*` to the same scale, so `blue-*` widgets follow it. A Theme Studio export sets `--ply-brand` and `--ply-scale-*`.

**Optional — custom brand color:** set `--ply-brand` in any stylesheet (load order does not matter), or copy a Theme Studio export:

```css
:root {
  --ply-brand: #7c3aed;
  --ply-brand-hover: #6d28d9;
  --ply-brand-active: #5b21b6;
}
```

Use [Theme Studio](https://ply-ui.com/theme/) (or the docs customizer) to live-preview those controls and export a full 50–950 scale as a Tailwind v4 `@theme` block. Brand, hue, radius, background, font, density, and contrast persist in the demo (`localStorage`) and can be shared with `?theme=nord&radius=0.75&bg=zinc&font=inter&density=compact`.

### 3. Add components

```bash
npx ply-ui-cli add button card dialog
```

Omit the name (`npx ply-ui-cli add`) in a terminal to pick from the catalog. Pass names plus `--yes` in CI and for agents.

Component dependencies are resolved recursively, and missing npm packages are installed with your package manager automatically. Run `npx ply-ui-cli list` to see everything that's available.

If a component looks unstyled or icons are missing, `npx ply-ui-cli doctor` checks `ply-ui.json`, Tailwind, CDK, and the icon sprites (read-only). Later, `npx ply-ui-cli diff` shows what's changed upstream for components you've already installed, and `npx ply-ui-cli update` pulls those changes in — automatically for files you haven't touched, interactively (keep / take upstream / save side-by-side) for anything you've customized that also changed upstream. See [`packages/cli`](packages/cli) for details.

### 4. Import in your Angular app

All components are **standalone** — import them from your local components folder:

```typescript
// app.component.ts (standalone)
import { CardComponent } from './components/card/card.component';
import { BaseButtonDirective } from './components/button/button.directive';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CardComponent, BaseButtonDirective],
  template: `...`,
})
export class AppComponent {}
```

---

## 💎 Ply Pro

Pro components are the pre-built blocks — blog and article cards, ecommerce blocks, media and social widgets, 18 full page layouts — plus advanced widgets (data table, date pickers, command palette, mega menu, file upload, multi-select, rich text editor, crop image, product gallery, tree, mention input, splitter).

After purchasing a license at [ply-ui.com](https://ply-ui.com), set your license key once and add pro components with the same CLI:

```bash
export PLY_LICENSE_KEY=your-license-key
npx ply-ui-cli add layout-dashboard blog-card-gradient-hero
```

The key is validated server-side by the pro registry on every fetch. In CI, set `PLY_LICENSE_KEY` as a secret.

---

## 🛍️ Templates

Templates are complete, production-grade applications built on Pro — every route wired up, shipped as source you own. Each bundle includes a Ply Pro license.

- **[Motif](https://ply-ui.com/templates/motif)** — an Angular 22 + Tailwind commerce storefront: mega menu, category listing, product detail, cart, checkout, order tracking and an editorial journal. **$149** including Pro. [Live demo](https://commerce-template.ply-ui.com/)
- **[Motif Admin](https://ply-ui.com/templates/motif-admin)** — the matching commerce operations dashboard: overview KPIs, orders, inventory, customers, analytics and settings. **$149** including Pro. [Live demo](https://dashboard-template.ply-ui.com/overview)
- **[Relay](https://ply-ui.com/templates/relay)** — a Linear-style Angular 22 + Tailwind team workspace: projects, kanban, issues, inbox, calendar, files and docs. **$149** including Pro. [Live demo](https://relay-template.ply-ui.com/overview)
- **Motif Suite** — Motif + Motif Admin + one Pro license for **$169** (save $129 vs buying separately).

---

## 📦 What's included

| Category | Free | Pro |
| --- | --- | --- |
| **UI primitives** | 50+ (buttons, inputs, dialogs, hover cards, menubars, currency, kbd, tabs, calendar, stacked toasts, …) | data table, date pickers, command palette, mega menu, file upload, multi-select, rich text editor, crop image, product gallery, tree, mention input, splitter |
| **Form blocks** | all 19 (login, signup, checkout, billing, wizard, …) | — |
| **Blocks & widgets** | — | blog/article cards, ecommerce blocks, media + social widgets |
| **Page layouts** | — | 18 (dashboard, kanban, inbox, docs, admin table, …) |
| **Directives, services, utils** | all | — |
| **Icons** | 390 SVG sprite icons | — |
| **Templates** | — | [Motif](https://ply-ui.com/templates/motif) storefront, [Motif Admin](https://ply-ui.com/templates/motif-admin) dashboard, [Relay](https://ply-ui.com/templates/relay) workspace ($149 each, or Motif Suite $169) |

---

## 🔧 Development (this repository)

Free component source lives in `components/`. CLI and MCP source live in `packages/`. Pro components are **not** in this repository.

```bash
npm ci
npm test
npm run lint
npm test --prefix packages/cli
npm test --prefix packages/mcp
```

Pull requests: see [CONTRIBUTING.md](CONTRIBUTING.md). Free, CLI, and MCP PRs **merge on this repository**. A private docs/Pro tree imports `main` afterwards so ply-ui.com and npm stay in sync.

## 📋 Requirements

- **Node.js** 22+
- **Angular** 22+ on `main`. Free-tier source for **Angular 19+** is on [`compat/angular-19`](https://github.com/ply-ui-ng/ply/tree/compat/angular-19) (same `components/`, without signal-forms `[formField]`).
- **Tailwind CSS** 4.x

### Server-side rendering

Components are safe to server-render or prerender. Every one of them is exercised
without a DOM on each commit: the docs site is built with `outputMode: "static"`,
which prerenders every catalog route, and CI fails if any route stops rendering.

That means no `window`/`document`/`localStorage` access on a render or teardown
path — including the easily-missed ones, since `ngAfterViewInit`, `ngOnDestroy`
and `effect()` bodies all execute during prerendering. The
[full write-up](https://ply-ui.com/learn/angular-ssr-safe-component-library/)
covers what broke when we turned it on.

If your app is browser-only, none of this costs you anything —