Getting Started

Follow the steps below to install the Base UI library in your Angular project.

Prerequisites

  • Node.js 22+ and npm.
  • Angular 22+ (standalone components, signals, zoneless-ready).
  • Tailwind CSS 4.x installed in your project.

Free Tier

Base UI provides a generous Free Tier of 119 items — every essential component (buttons, cards, dialogs, hover cards, menubars, inputs, currency fields, selects, toasts, etc.) and all 19 form blocks — usable immediately without any account or license!

✨ See the Free Tier in action Explore a complete Admin Dashboard built exclusively with free components. Check out the Live Demo, grab the source code from the GitHub Repository, or duplicate the official Figma Design System.

1) Initialize the CLI

Run the init command to configure your project for Base UI components:

bash

npx base-ui-cli init

2) Add Components

Use the CLI to add specific free components directly into your project. For example, to add a button:

bash

npx base-ui-cli add button

3) AI agents (MCP) — free tier

Base UI ships an open Model Context Protocol server so coding agents can search and install free components with tools (list_components, search_components, get_component, add_components) instead of guessing CLI commands. The CLI remains the canonical installer — MCP wraps it. No license key is required for free components.

Works with any MCP-compatible client, including:

  • Cursor — Settings → MCP, or project .cursor/mcp.json
  • Claude (Claude Code / Desktop) — claude mcp add or Claude Desktop MCP config
  • ChatGPT — Connected Apps / Developer Mode MCP (remote URL when you host HTTP; stdio via local coding agents)
  • Gemini — MCP-capable Google / Gemini coding agents and IDEs that accept stdio or remote MCP
  • Kimi (Kimi Code CLI) — kimi mcp add / ~/.kimi/mcp.json (stdio or HTTP)
  • VS Code (GitHub Copilot), Windsurf, and other MCP hosts

Today’s package is stdio (local process) — ideal for IDE / CLI agents (Cursor, Claude Code, Kimi Code, VS Code, Windsurf). ChatGPT and Gemini chat apps often prefer a remote MCP URL; hosted HTTP ships in a later phase. Until then those users can still follow llms.txt + the CLI, or use an IDE agent with the config below.

Shared stdio config (Cursor .cursor/mcp.json, VS Code / Windsurf MCP JSON, Claude Desktop, Kimi mcp.json — same shape):

json

{
  "mcpServers": {
    "base-ui": {
      "command": "npx",
      "args": ["-y", "base-ui-mcp"],
      "env": {
        "BASE_UI_CWD": "${workspaceFolder}"
      }
    }
  }
}

Cursor: reload the window (Cmd/Ctrl+Shift+P → Developer: Reload Window) and confirm Settings → MCP shows base-ui connected. Claude Code:claude mcp add --transport stdio base-ui -- npx -y base-ui-mcp (set BASE_UI_CWD to your app root). Kimi Code:kimi mcp add --transport stdio base-ui -- npx -y base-ui-mcp with -e BASE_UI_CWD=/path/to/app. Run npx base-ui-cli init --yes in the project first so add_components has a place to write files.

Example prompts (any MCP client):

  • “Using Base UI MCP, search for dialog components and list free form blocks.”
  • “Using Base UI MCP, add the free button and card components to this project.”

Package: base-ui-mcp. Pro installs via MCP (license key) ship in a later phase — until then use the CLI with BASE_UI_LICENSE_KEY. Details: base-ui-mcp · Why LLMs write better code with copy-in UI · GitHub.

Cookbooks

After install, assemble real screens from the cookbooks: a settings form, dialog + CVA, invoice table (data-table selection, resize, server page/sort), AI chat, and Angular 22 signal forms. Component playgrounds also include Open in StackBlitz.

Premium Package

Pro components are the pre-built blocks — blog and article cards, ecommerce blocks, media and social widgets, full page layouts — plus the unified shell (page and dashboard modes) and advanced widgets like the data table, rich text editor, file upload, and command palette. Free apps can still ship with sidenav, scroll-nav, and page-main. A license unlocks all Pro items, with lifetime updates. Track what ships at base-ui.net/changelog.

1) Set your license key

After purchase you receive a license key by email. Set it once as an environment variable — the CLI sends it to the pro registry, where it is validated on every fetch:

bash

export BASE_UI_LICENSE_KEY=your-license-key

(In CI, add BASE_UI_LICENSE_KEY as a secret. On Windows, use setx BASE_UI_LICENSE_KEY your-license-key.)

2) Add Pro Components

Then add any pro component or block with the same CLI:

bash

npx base-ui-cli add layout-dashboard

3) Stay updated

Lifetime Pro updates ship continuously. See what changed on the changelog, then pull upstream component changes into your project:

bash

npx base-ui-cli update

The CLI also notifies you after add when a newer base-ui-cli is on npm.

Tailwind CSS Setup

Base UI works with standard Tailwind CSS 4. Components use standard Tailwind spacing (p-4) and standard color utilities. The color="primary" input maps to blue-500 — no custom theme setup required.

1) Install Tailwind CSS 4

Follow the official Tailwind installation guide for Angular. You need tailwindcss, @tailwindcss/postcss, and a PostCSS config.

2) Minimal src/tailwind.css

Register this file in angular.jsonbefore your global SCSS:

css

@import "tailwindcss";

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

3) Custom brand color (optional)

To change the default blue brand, override Tailwind's blue scale. Components keep using blue-* / color="primary":

css

:root {
  --color-blue-500: rgb(139 92 246);
  --color-blue-600: rgb(124 58 237);
      /* ...full scale from theme customizer export */
}

The live docs customizer (palette, radius, background, font, density) persists across reloads and can be shared with a URL such as ?theme=violet&radius=0.75&bg=zinc&font=inter&density=compact. Light/dark mode is separate. Export the CSS from the customizer to copy the blue scale into your app.

Zero-config default: skip step 3 entirely — stock Tailwind blue is the brand color out of the box.

Usage

The library provides Standalone Components, Directives, and Pipes. You import them directly from your local components folder where the CLI placed them.

Example: Using a Button

In your component file (app.component.ts):

typescript

import { Component } from '@angular/core';
import { BaseButtonDirective } from './components/button/base-button.directive';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [BaseButtonDirective],
  template: `
    <button base-button>Click Me!</button>
  `
})
export class AppComponent {}

Enjoy building beautiful interfaces!