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 and Chalk 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';

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' or 'chalk'. 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/.