Follow the steps below to install the Base UI library in your Angular project.
Base UI provides a generous Free Tier of 125 items — every essential component (buttons, cards, dialogs, hover cards, menubars, inputs, currency fields, selects, stacked 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
Run the init command to configure your project for Base UI components:
npx base-ui-cli init
Use the CLI to add specific free components directly into your project. For example, to add a button:
npx base-ui-cli add button
Or run npx base-ui-cli add with no name to pick from the catalog — filter by All, Free, Pro, or a registry category, then type to filter and Space to select. Agents and CI should pass names plus --yes so the picker does not hang.
If a component looks unstyled or icons are missing, run the doctor command. It is read-only. It checks base-ui.json, the Angular workspace, @angular/cdk, Tailwind v4 and its @source paths, the base-ui.css import, icon sprites, and the components directory. Finish Tailwind CSS Setup below if those checks fail:
npx base-ui-cli doctor
Base UI ships an open Model Context Protocol server. There are two modes — they are not interchangeable:
https://mcp.base-ui.net/mcp. Tools: list_components, search_components, get_component. This host cannot write to your disk. To install, copy npx base-ui-cli add <name> into the project. Enable Developer mode (Settings → Login and security), add the URL under Plugins, then in each new chat attach it via + → More → Developer mode → Base UI. npx -y base-ui-ng-mcp. Same catalog tools, plus add_components, init_project, doctor, diff_components, update_components. The CLI remains the canonical installer — MCP wraps it. No license key is required for free components. Self-host a catalog URL with npx -y base-ui-ng-mcp --http --read-only (optional BASE_UI_MCP_AUTH_TOKEN). Users without MCP can still follow llms.txt + the CLI.
Shared stdio config (Cursor .cursor/mcp.json, VS Code / Windsurf MCP JSON, Claude Desktop, Kimi mcp.json — same shape):
{
"mcpServers": {
"base-ui": {
"command": "npx",
"args": ["-y", "base-ui-ng-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-ng-mcp (set BASE_UI_CWD to your app root). Kimi Code:kimi mcp add --transport stdio base-ui -- npx -y base-ui-ng-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:
button and card components to this project.” Package: base-ui-ng-mcp. Pro add uses BASE_UI_LICENSE_KEY on the MCP process (or licenseKey on the tool). Details: base-ui-ng-mcp · Why LLMs write better code with copy-in UI · GitHub.
Many Cursor and Windsurf users never start a local MCP server. Drop a project rule so the assistant still writes standalone, zoneless Angular 22 with Base UI selectors and Tailwind v4 dark: pairs. npx base-ui-cli init writes these files when they are missing.
.cursor/rules/base-ui.mdc (legacy: .cursorrules) .windsurf/rules/base-ui.md.vscode/base-ui.code-snippets — type base-card or base-dialog after npx base-ui-cli add has copied the component in. Raw files: base-ui.mdc · base-ui.code-snippets. Snippets expand usage markup, not the component source — the CLI remains the install path.
After install, assemble real screens from the cookbooks: a settings form, dialog + CVA, invoice table, AI chat, and Angular 22 signal forms. Component playgrounds, cookbooks, and blocks include Open in StackBlitz.
Component docs open on a live Preview, with Code for the template, TypeScript class, and npx base-ui-cli add … line. Use Copy as AI prompt or Copy MCP install at the top of a page; many pages also include a knob playground.
Base UI is signal-first and zoneless-ready. These recipes show the modern Angular APIs on the same components:
form() + [formField] on inputs, select, and toggle (also as code tabs on those component pages). base-data-table, async combobox, and virtual-scroll without a handwritten RxJS pipeline. base-skeleton as the placeholder. document.startViewTransition() for tabs and dialogs, or Angular withViewTransitions() on the router. Pro components are the pre-built blocks — blog and article cards, ecommerce blocks, media and social widgets, 18 full page layouts (including a Linear-style workspace inbox) — 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.
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:
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.)
Then add any pro component or block with the same CLI. Bare npx base-ui-cli add also lists Pro items in the catalog picker (they still need the license key):
npx base-ui-cli add layout-dashboard layout-inbox-workspace
Lifetime Pro updates ship continuously. See what changed on the changelog, then pull upstream component changes into your project:
npx base-ui-cli update
The CLI also notifies you after add when a newer base-ui-cli is on npm.
Base UI works with standard Tailwind CSS 4. Components use standard Tailwind spacing (p-4) and standard color utilities. color="primary" reads --base-primary from base-ui.css (CLI init writes the defaults). Theme Studio live-preview and Copy CSS write the same variables — unmigrated widgets still follow --color-blue-*.
Follow the official Tailwind installation guide for Angular. You need tailwindcss, @tailwindcss/postcss, and a PostCSS config.
src/tailwind.css Register this file in angular.jsonbefore your global SCSS:
@import "tailwindcss";
@source "./src/**/*.{html,ts}"; Buttons and inputs read --base-primary from base-ui.css. Override those tokens (Theme Studio Copy CSS writes them). Unmigrated widgets still follow Tailwind blue-*:
:root {
--base-primary: rgb(124 58 237);
--base-primary-hover: rgb(109 40 217);
--base-primary-active: rgb(91 33 182);
--base-ring: rgb(124 58 237);
--color-blue-500: rgb(139 92 246);
--color-blue-600: rgb(124 58 237);
} The live docs customizer (palette, radius, background, font, density, hue, contrast) persists across reloads and can be shared with a URL such as ?theme=nord&radius=0.75&bg=zinc&font=inter&density=compact. Light/dark mode is separate. Open Theme Studio and copy the Tailwind v4 @theme block into src/tailwind.css.
Zero-config default: skip step 3 entirely — stock Tailwind blue is the brand color out of the box.
The library provides Standalone Components, Directives, and Pipes. You import them directly from your local components folder where the CLI placed them.
In your component file (app.component.ts):
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 {} Empty states, paginator labels, and icon-only dialog close buttons default to English. Override them once in app.config.ts. Per-instance inputs like emptyMessage still win. This is not ngx-translate for your catalog copy.
import { provideBaseUiI18n } from './components/i18n/i18n';
export const appConfig: ApplicationConfig = {
providers: [
provideBaseUiI18n({
close: 'Fermer',
noDataAvailable: 'Aucune donnée',
noResults: 'Aucun résultat',
}),
],
}; Install with npx base-ui-cli add i18n. Adding data-table, combobox, dialog, or paginator also copies it as a dependency.
Icon sprites default to assets/icons.svg and assets/icons-filled.svg. Override the paths (and optional default icon size) once in app.config.ts. Per-instance [path], [filledPath], and [size] still win. w-* / h-* classes keep class-based sizing.
import { provideBaseUI } from './components/config/config';
export const appConfig: ApplicationConfig = {
providers: [
provideBaseUI({
iconPath: 'assets/icons.svg',
filledIconPath: 'assets/icons-filled.svg',
defaultSize: 20,
}),
],
}; Install with npx base-ui-cli add config. Adding icon also copies it as a dependency.
data-table, custom-select, and dialog ship Angular CDK ComponentHarness classes in the same folder as the component. They copy in with npx base-ui-cli add — there is no separate registry item. Use TestbedHarnessEnvironment.loader(fixture). Dialog overlays are appended to document.body, so use documentRootLoader(fixture).
import { TestbedHarnessEnvironment } from '@angular/cdk/testing/testbed';
import { DataTableHarness } from './components/data-table/data-table.harness';
import { DialogHarness } from './components/dialog/dialog.harness';
const loader = TestbedHarnessEnvironment.loader(fixture);
const table = await loader.getHarness(DataTableHarness);
const dialogs = TestbedHarnessEnvironment.documentRootLoader(fixture);
const dialog = await dialogs.getHarness(DialogHarness);Enjoy building beautiful interfaces!