NgStarter UI

NgStarter UI components and admin templates are free and open source under the MIT License. Use, modify, and distribute them in your projects while retaining the copyright and permission notice.

NgStarter UI is an Angular component kit for admin panels and product dashboards. The component package is published as @ngstarter-ui/components and is organized around secondary entry points such as @ngstarter-ui/components/button, @ngstarter-ui/components/dialog, and @ngstarter-ui/components/table.

Installation

The current package targets Angular 22 and Angular CDK 22. Use SCSS for the application's global styles.

For a new Angular 22 project, create the app with SCSS and add NgStarter UI:

npx @angular/cli@22 new project-name --style=scss
cd project-name
npx ng add @ngstarter-ui/components

For an existing Angular 22 app, run the same schematic from your project root:

npx ng add @ngstarter-ui/components

The ng add schematic installs the required dependencies, configures Tailwind CSS 4 and PostCSS, imports the Default theme, adds provideNgsTheme to the application config, and adds the DM Sans font to the application HTML. In a workspace with multiple applications, select the target with --project=your-app.

The schematic also adds NgStarter guidance to AGENTS.md and installs a local Codex skill at .codex/skills/ngstarter-ui by default. To skip the local skill installation while keeping the AGENTS.md guidance, run:

npx ng add @ngstarter-ui/components --codex-skill=false

If NgStarter UI is already installed and you only want to add or refresh the Codex skill, run:

npx ng generate @ngstarter-ui/components:codex-skill

Basic Usage

NgStarter components are standalone Angular components. Import each component from its public secondary entry point and include it in the component's imports:

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { Button } from '@ngstarter-ui/components/button';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [Button],
  template: `<button ngsButton="filled">Save</button>`,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class Example {}

Other entry points follow the same pattern, such as @ngstarter-ui/components/dialog, @ngstarter-ui/components/form-field, and @ngstarter-ui/components/input.

Theming

NgStarter ships Default, Chalk, and Mono themes, each with light and dark colors. Import the Default theme once in the application's global styles.scss:

@use '@ngstarter-ui/components/styles/themes/default';

If the application uses Chalk or lets users switch to it at runtime, also import:

@use '@ngstarter-ui/components/styles/themes/chalk';

For the Mono theme, import its stylesheet and select theme: 'mono':

@use '@ngstarter-ui/components/styles/themes/mono';

provideNgsTheme({ theme: 'mono', colorScheme: 'auto' });

Mono maps the shadcn/ui Neutral palette to NgStarter tokens, with monochrome actions, subtle borders, compact controls, and light/dark surfaces. It can also be imported on its own when the app only uses this theme. Select it before bootstrap with data-ngs-theme="mono" to avoid a flash of the default palette.

The theme includes Tailwind CSS and shared base styles; an additional Tailwind import or a duplicate CSS reset is not needed.

Themes use fixed light and dark color tokens. Their main layers are:

• primitive tokens: spacing, radius, font sizes, shadows
• semantic tokens: --ngs-color-primary, --ngs-color-surface, --ngs-color-danger
• component tokens: --ngs-button-height, --ngs-field-radius, --ngs-table-row-height

Configure the theme and color scheme at runtime:

import { ApplicationConfig } from '@angular/core';
import { provideNgsTheme } from '@ngstarter-ui/components/core';

export const appConfig: ApplicationConfig = {
  providers: [
    provideNgsTheme({
      theme: 'default',
      colorScheme: 'auto',
    }),
  ],
};

theme accepts 'default', 'chalk', or 'mono'. colorScheme accepts 'light', 'dark', or 'auto'; auto follows the operating system preference. These options default to 'default' and 'auto', respectively.

colorPreset is optional and currently supports only 'default'. The theme manager always uses that value, so it can be omitted. Customize colors and geometry through CSS tokens.

Preferences are stored in localStorage under ngs-admin by default. Set persist: false to disable persistence or use storageKey to choose another key. Stored preferences take precedence over the initial theme and color scheme when persistence is enabled.

Use ThemeManagerService to change preferences from a component:

import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { Button } from '@ngstarter-ui/components/button';
import { ThemeManagerService } from '@ngstarter-ui/components/core';

@Component({
  selector: 'app-theme-preferences',
  standalone: true,
  imports: [Button],
  template: `
    <button ngsButton (click)="themeManager.setTheme('chalk')">Chalk</button>
    <button ngsButton (click)="themeManager.setColorScheme('auto')">System theme</button>
    <button ngsButton (click)="themeManager.setColorScheme('dark')">Dark mode</button>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ThemePreferences {
  readonly themeManager = inject(ThemeManagerService);
}

The service synchronizes document attributes and the dark class. Without the runtime service, the imported stylesheets can also be controlled with document attributes:

<html data-ngs-theme="chalk" data-ngs-color-scheme="dark">

Component Demos

The documentation site includes live demos and API examples for each component:

• Documentation
• Installation
• Theming
• AI component registry

The package also includes the registry at node_modules/@ngstarter-ui/components/ai/component-registry.json for local component discovery and AI-assisted development.

Forms

• Autocomplete
• Button
• Button Toggle
• Checkbox
• Country Select
• Currency Select
• Date Format Select
• Filter Select
• Inline Text Edit
• Input
• Input Mask
• Input Validator
• Number Input
• Password Strength
• Phone Input
• Pin Input
• Radio
• Segmented
• Select
• Slide Toggle
• Timezone Select

Navigation

• Breadcrumbs
• Navigation
• Rail Navigation
• Sidebar
• Side Panel
• Tab Panel

Data, Layout, And Libraries

• Content Editor
• Data View
• Form Builder
• Headless Editor
• Image Designer
• Kanban Board
• Micro Charts
• Bar Chart
• Line Chart
• Pie Chart
• PDF Builder
• PDF Signer
• PDF Viewer
• Video Player
• Visual Builder

Components

• Action Required
• Alert
• Announcement
• Avatar
• Badge
• Block Loader
• Bottom Sheet
• Calendar
• Card
• Card Overlay
• Carousel
• Chips
• Code Highlighter
• Color Picker
• Color Switcher
• Command Bar
• Comment Editor
• Comparison Slider
• Confirm
• Cookie Popup
• Crop
• Datepicker
• Digit Roller
• Dialog
• Divider
• Drawer
• Emoji Picker
• Empty State
• Events
• Expand
• Expansion Panel
• File Type
• Filter Builder
• Gauge
• Grid
• Guided Tour
• Headless Stepper
• Icon
• Image Placeholder
• Image Resizer
• Image Viewer
• Image Zoom Viewer
• Incidents
• Kbd
• Layout
• List
• Marquee
• Menu
• Notifications
• Paginator
• Panel
• Popover
• Progress Bar
• Progress Spinner
• Resizable Container
• Screen Loader
• Sidenav
• Signature Pad
• Skeleton
• Slider
• Snack Bar
• Sort
• Split Pane
• Step Tracker
• Stepper
• Suggestions
• Table
• Tabs
• Thumbnail Maker
• Tiles
• Timeline
• Timepicker
• Toolbar
• Tooltip
• Tree
• Typed Signature Pad
• Upload
• Video Viewer

Repository Development

Clone the repository and install its dependencies to run the docs locally:

git clone https://github.com/elementarlabsdev/ngstarter.git
cd ngstarter
npm ci
npm run start:docs

The workspace contains:

| Directory | Purpose | | --- | --- | | projects/components | Publishable library, secondary entry points, themes, and schematics | | projects/docs | Documentation application and live component examples | | projects/admin | Admin demo application | | projects/admin-modern | Modern admin application | | projects/admin-corporate | Corporate admin application | | projects/admin-classic | Placeholder for a future admin application |

Use the relevant command for the part of the workspace you are changing:

| Command | Purpose | | --- | --- | | npm run build:components:prod | Build the library, AI metadata, and schematics | | npm run verify:components:package | Validate the generated package after building it | | npm run build:docs:prod | Build the documentation application | | npm run start:admin:modern | Run the Modern admin application | | npm run start:admin:corporate | Run the Corporate admin application | | npm run verify:admin:components | Check admin composition against NgStarter conventions | | npm run test:components | Run library unit tests | | npm run test:docs | Run documentation application tests | | npm run test | Run all configured unit test targets | | npm run generate:ai | Regenerate the AI component registry and usage guidance |

Follow AGENTS.md for component structure, public imports, admin composition, and validation. Keep changes in source files; do not edit generated files under dist/.