Skip to content
Xng UI
Docs CDK Components Tools Contribute About

Getting started

@xngui/components/button
@xngui/components/button

Install @xngui, bootstrap with provideX(), import styles, and render your first component.

Installation

Install packages

Add the core packages your app needs. Individual components are tree-shaken via flat entry imports.

terminal
pnpm add @xngui/components @xngui/styles @xngui/theme @xngui/core @xngui/icons

Peer: Angular 22+. Zoneless change detection is recommended — call provideZonelessChangeDetection() in app.config.ts.

App bootstrap

provideX()

Registers global defaults (size, density, validateOn), locale, logging, and error handling.

app.config.ts
import { ApplicationConfig, provideZonelessChangeDetection } from '@angular/core';import { provideRouter } from '@angular/router';import { provideX } from '@xngui/core/config';export const appConfig: ApplicationConfig = {  providers: [    provideZonelessChangeDetection(),    provideX({      config: {        size: 'md',        density: 'standard',        validateOn: 'touched',      },      locale: 'en-US',    }),    provideRouter(routes),  ],};

Styles & theme

Global stylesheet

Import foundation tokens once in your app global CSS. Add the icon font when using <x-icon>.

styles.css
@import '@xngui/styles';@import '@xngui/icons/fontawesome';
Dark mode & palettes

XThemeService toggles .dark on <html> (light / dark / system). XPaletteService applies primitive color ramps via a :root block in <head>. See Styles for the full API.

theme.ts
import { XPaletteService, XThemeService } from '@xngui/theme';inject(XThemeService).setMode('dark');inject(XPaletteService).setPalette('ocean');
Custom palette

Ship your own ramp at bootstrap with provideXPalettes() — token keys may omit the -- prefix.

palettes.ts
import { provideXPalettes } from '@xngui/theme';provideXPalettes([  {    id: 'brand',    label: 'Brand',    description: 'Company colors.',    icon: '🎨',    tokens: { 'x-primary-500': 'oklch(0.55 0.14 250)' },  },]);

First component

Button + icon

Import the component class, add it to imports, and use the x- selector in your template.

app.ts
import { Component } from '@angular/core';import { XButton } from '@xngui/components/button';import { XIcon } from '@xngui/icons';@Component({  selector: 'app-root',  imports: [XButton, XIcon],  template: `    <x-button variant="primary">      <x-icon name="star" xStart >      Get started    <x-button>  `,})export class App {}

Flat imports

Import paths

Category folders (actions/, forms/) organize source on disk only — never in the import path.

SymbolImport path
XButton@xngui/components/button
XInput@xngui/components/input
XForm@xngui/components/form
XIcon@xngui/icons
XDataSource@xngui/cdk/datasource
XSize@xngui/core
provideX@xngui/core/config
XThemeService@xngui/theme
XPaletteService@xngui/theme
provideXPalettes@xngui/theme

Next steps

Continue learning
  • Forms guide

    Signal Forms, x-form, and x-form-field composition.

  • Styles

    CSS primitives, semantic roles, and interaction states.

  • Themes

    Runtime appearance, palette presets, and custom brand ramps.

  • Core types

    Shared unions, events, and app bootstrap.

  • Icons

    XIcon, Font Awesome import, and size tokens.

  • Testing

    Harnesses, specs, and configureXComponent for library contributors.

  • Theme builder

    Tune tokens and export a CSS preset.

  • Components

    Interactive demos for every UI primitive.