# Zard UI

> Zard UI is a collection of beautifully-designed, accessible Angular components built with TypeScript, TailwindCSS v4, and Class Variance Authority (CVA). Inspired by shadcn/ui, it provides a modern component library with signal-based inputs, OnPush change detection, and type-safe styling variants. Open Source. Open Code. AI-Ready.

## Overview

- [Home](https://zardui.com/): Main landing page showcasing Zard UI features and capabilities.
- [Documentation](https://zardui.com/docs): Complete documentation for Zard UI components and guides.
- [Components](https://zardui.com/docs/components): Browse all available components in the library.
- [Blocks](https://zardui.com/blocks): Pre-built component compositions and templates.
- [Colors](https://zardui.com/colors): Tailwind color palette reference in all formats.
- [Typeset](https://zardui.com/typeset): Build a typography preset for rendered markdown and take away the CSS.

## Get Started

- [Introduction](https://zardui.com/docs/introduction): Core principles, architecture overview, and getting started with Zard UI.
- [Installation](https://zardui.com/docs/installation): Step-by-step guide to install Zard UI in your Angular project.
- [Components JSON](https://zardui.com/docs/components-json): Configuration file for customizing the CLI and component installation.
- [Theming](https://zardui.com/docs/theming): Guide to customizing colors, typography, and design tokens with TailwindCSS v4.
- [Typeset](https://zardui.com/docs/typeset): One CSS file that styles HTML and rendered markdown, governed by size, leading and flow.
- [Pre-processors](https://zardui.com/docs/pre-processors): Understanding SCSS/Sass integration with Tailwind v4 - risks, limitations, and alternatives.
- [Dark Mode](https://zardui.com/docs/dark-mode): Implementing dark mode in your Angular application.
- [CLI](https://zardui.com/docs/cli): Command-line tool for installing and managing Zard UI components.
- [Figma](https://zardui.com/docs/figma): Figma design resources and component library.
- [Changelog](https://zardui.com/docs/changelog): Release notes, version history, and updates.
- [About](https://zardui.com/docs/about): Credits, project information, and acknowledgments.

## Forms

- [Forms](https://zardui.com/docs/forms): Overview of the three ways to build forms in Angular with Zard UI, and how to pick one.
- [Signal Forms](https://zardui.com/docs/forms/signal-forms): Building forms with the signal-based `@angular/forms/signals` API — schema, validation, errors, field types and array fields.
- [Reactive Forms](https://zardui.com/docs/forms/reactive-forms): Building forms with `FormGroup`/`FormControl`/`FormArray` — typed models, validators, errors, field types and array fields.
- [Template-driven Forms](https://zardui.com/docs/forms/template-driven-forms): Building forms with `ngModel` and validation attributes — the simplest approach, plus its limits.

## Utilities

- [Scroll Fade](https://zardui.com/docs/utils/scroll-fade): Fading the edges of a scroll container in sync with the scroll position, with no JavaScript.
- [Shimmer](https://zardui.com/docs/utils/shimmer): A sweeping highlight across text, for the seconds where something is being generated.

## Components

### Form & Input

- [Button](https://zardui.com/docs/components/button): Displays a button or a component that looks like a button.
- [Button Group](https://zardui.com/docs/components/button-group): Groups buttons together.
- [Calendar](https://zardui.com/docs/components/calendar): A calendar component that allows users to select a date or a range of dates.
- [Checkbox](https://zardui.com/docs/components/checkbox): A control that allows the user to toggle between checked and not checked.
- [Combobox](https://zardui.com/docs/components/combobox): Autocomplete input and command palette with a list of suggestions.
- [Date Picker](https://zardui.com/docs/components/date-picker): A button that opens a calendar in a popover to pick one date, several dates, or a date range.
- [Field](https://zardui.com/docs/components/field): Composable building blocks for accessible form layouts with labels, descriptions and errors.
- [Input](https://zardui.com/docs/components/input): Displays a form input field or a component that looks like an input field.
- [Input Group](https://zardui.com/docs/components/input-group): Groups input elements together with addons.
- [Input OTP](https://zardui.com/docs/components/input-otp): Accessible one-time password component with copy-paste functionality.
- [Radio Group](https://zardui.com/docs/components/radio-group): A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time.
- [Select](https://zardui.com/docs/components/select): Displays a list of options for the user to pick from — triggered by a button.
- [Slider](https://zardui.com/docs/components/slider): An input where the user selects a value from within a given range.
- [Switch](https://zardui.com/docs/components/switch): A control that allows the user to toggle between checked and not checked.
- [Textarea](https://zardui.com/docs/components/textarea): Displays a multi-line text input field.

### Layout & Navigation

- [Accordion](https://zardui.com/docs/components/accordion): A vertically stacked set of interactive headings that each reveal a section of content.
- [Aspect Ratio](https://zardui.com/docs/components/aspect-ratio): Displays content within a desired ratio.
- [Breadcrumb](https://zardui.com/docs/components/breadcrumb): Displays the path to the current resource using a hierarchy of links.
- [Collapsible](https://zardui.com/docs/components/collapsible): An interactive component which expands and collapses a panel.
- [Navigation Menu](https://zardui.com/docs/components/navigation-menu): A collection of links for navigating websites.
- [Pagination](https://zardui.com/docs/components/pagination): Pagination with page navigation, next and previous links.
- [Resizable](https://zardui.com/docs/components/resizable): Accessible resizable panel groups and layouts with keyboard support.
- [Separator](https://zardui.com/docs/components/separator): Visually or semantically separates content.
- [Sidebar](https://zardui.com/docs/components/sidebar): A composable, themeable and customizable sidebar component.
- [Tabs](https://zardui.com/docs/components/tabs): A set of layered sections of content — known as tab panels — that are displayed one at a time.

### Overlays & Dialogs

- [Alert Dialog](https://zardui.com/docs/components/alert-dialog): A modal dialog that interrupts the user with important content and expects a response.
- [Command](https://zardui.com/docs/components/command): Fast, composable, unstyled command menu.
- [Context Menu](https://zardui.com/docs/components/context-menu): Displays a menu of actions triggered by a right click.
- [Dialog](https://zardui.com/docs/components/dialog): A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.
- [Drawer](https://zardui.com/docs/components/drawer): A draggable panel that slides in from an edge of the screen.
- [Dropdown](https://zardui.com/docs/components/dropdown): Displays a menu to the user — such as a set of actions or functions — triggered by a button.
- [Hover Card](https://zardui.com/docs/components/hover-card): For sighted users to preview content available behind the link.
- [Popover](https://zardui.com/docs/components/popover): Displays rich content in a portal, triggered by a button.
- [Sheet](https://zardui.com/docs/components/sheet): Extends the Dialog component to display content that complements the main content of the screen.
- [Tooltip](https://zardui.com/docs/components/tooltip): A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.

### Feedback & Status

- [Alert](https://zardui.com/docs/components/alert): Displays a callout for user attention.
- [Badge](https://zardui.com/docs/components/badge): Displays a badge or a component that looks like a badge.
- [Empty](https://zardui.com/docs/components/empty): Empty state placeholder when there is no data.
- [Progress](https://zardui.com/docs/components/progress): Displays an indicator showing the completion progress of a task.
- [Skeleton](https://zardui.com/docs/components/skeleton): Use to show a placeholder while content is loading.
- [Sonner](https://zardui.com/docs/components/sonner): An opinionated toast component for Angular.
- [Spinner](https://zardui.com/docs/components/spinner): Displays a loading spinner.

### Display & Media

- [Attachment](https://zardui.com/docs/components/attachment): Composable file and image attachment
- [Avatar](https://zardui.com/docs/components/avatar): An image element with a fallback for representing the user.
- [Bubble](https://zardui.com/docs/components/bubble): Displays conversational content in a message bubble. Supports variants, alignment, grouping, reactions, and collapsible content.
- [Card](https://zardui.com/docs/components/card): Displays a card with header, content, and footer.
- [Carousel](https://zardui.com/docs/components/carousel): A carousel with motion and swipe built using Embla.
- [Chart](https://zardui.com/docs/components/chart): Beautiful charts built with Apache ECharts. Copy and paste into your apps.
- [Marker](https://zardui.com/docs/components/marker): Displays an inline status, system note, bordered row, or labeled separator in a conversation.
- [Message](https://zardui.com/docs/components/message): Displays a message in a conversation, with optional avatar, header, footer, and alignment.
- [Table](https://zardui.com/docs/components/table): A responsive table component.

### Misc

- [Item](https://zardui.com/docs/components/item): A versatile component for displaying content with media, title, description, and actions.
- [Kbd](https://zardui.com/docs/components/kbd): Displays a keyboard key or shortcut.
- [Toggle](https://zardui.com/docs/components/toggle): A two-state button that can be either on or off.
- [Toggle Group](https://zardui.com/docs/components/toggle-group): A set of two-state buttons that can be toggled on or off.
## Contribute

- [Overview](https://zardui.com/docs/contribute): Why and how to contribute to Zard UI, with a quick start and a map of the guide.
- [Setup](https://zardui.com/docs/contribute/setup): Requirements, fork and clone, the dev server on port 4222, git hooks and essential commands.
- [Architecture](https://zardui.com/docs/contribute/architecture): What each project in the monorepo owns, how they connect, and every path alias.
- [Project Structure](https://zardui.com/docs/contribute/project-structure): Commented directory tree, a task-to-directory lookup, and which committed files are generated.
- [Components](https://zardui.com/docs/contribute/components): The component generator, the CVA pattern, demos, the API reference and the pre-PR checklist.
- [Blocks](https://zardui.com/docs/contribute/blocks): Scaffolding, syncing and registering a block, including screenshots and registry categories.
- [Documentation System](https://zardui.com/docs/contribute/documentation): The six Shiki generators, code fence metadata, page anatomy and the post-build Markdown pipeline.
- [Testing](https://zardui.com/docs/contribute/testing): Jest unit tests, Playwright E2E specs with accessibility checks, and the E2E governance rules.
- [Workflow](https://zardui.com/docs/contribute/workflow): Branch naming, the mandatory emoji commit format, the PR checklist and the CI jobs.
- [Release](https://zardui.com/docs/contribute/release): The automated release pipeline, version bump rules and the published packages.
- [FAQ & Troubleshooting](https://zardui.com/docs/contribute/faq): Rejected commits, empty code blocks, missing routes, alias errors and Nx cache issues.

## Installation

### Using CLI (Recommended)

```bash
npx zard-cli init
npx zard-cli add button
```

### Manual Installation

```bash
npm install class-variance-authority clsx tailwind-merge
```

Then copy component code from the documentation.

## Key Features

- 🎨 **Modern Design**: Beautiful, accessible components inspired by shadcn/ui
- ⚡ **Performance**: Signal-based inputs with OnPush change detection
- 🎯 **Type-Safe**: Full TypeScript support with CVA for styling variants
- 🌙 **Dark Mode**: Built-in dark mode support
- 📦 **Tree-Shakeable**: Import only what you need
- 🔧 **Customizable**: Easy theming with TailwindCSS v4
- ♿ **Accessible**: ARIA-compliant components
- 📱 **Responsive**: Mobile-first design approach

## Tech Stack

- Angular 19+
- TypeScript
- TailwindCSS v4
- Class Variance Authority (CVA)
- Angular CDK
- Lucide Icons

## License

MIT License - Open Source