ngx-align-ui

v0.4.8

Published

7 days ago

A library for aligning UI components in Angular applications.

0High
0Medium
0Low

nabijon.ibodullaev

ngx-align-ui

Angular adaptation of the AlignUI design system for Angular 21+ applications.

ngx-align-ui provides standalone Angular components, shared AlignUI design tokens, Tailwind v4-friendly styling, and helper utilities for building consistent interfaces.

What This Package Includes

Standalone Angular components for common product UI patterns
theme.css for AlignUI tokens, semantic colors, and shared motion utilities
styles.css for projects that want prebuilt CSS instead of compiling Tailwind
cn(...) for safe class composition with AlignUI-aware merging
tv(...) for typed variant factories backed by the same merge rules
Exported token objects and Tailwind config for advanced customization

Requirements

Angular 21+
Modern Angular standalone-component workflow
Tailwind CSS v4 if you want to compile the design tokens and utilities in your own app

Installation

Install the library and its peer dependencies:

npm install ngx-align-ui clsx tailwind-merge tailwind-variants @tanstack/angular-table

If you do not use the table primitives, keeping @tanstack/angular-table installed is still safe.

Styling Setup

ngx-align-ui ships with two CSS entry points:

ngx-align-ui/theme.css for Tailwind v4 projects
ngx-align-ui/styles.css for projects that want ready-to-use compiled CSS

Option A: Tailwind CSS v4 Project

This is the recommended integration path.

Install Tailwind tooling in your Angular app:

npm install -D tailwindcss @tailwindcss/postcss postcss

Create or update .postcssrc.json:

{
  "plugins": {
    "@tailwindcss/postcss": {}
  }
}

Import Tailwind and the AlignUI theme in your global stylesheet, usually src/styles.css:

@import 'tailwindcss';
@import 'ngx-align-ui/theme.css';

Make sure your app includes that stylesheet in angular.json.

theme.css includes the AlignUI CSS variables, Tailwind v4 token registration, semantic utility support, Remix Icon styles, and the shared motion utilities used by overlays and accordions.

Dark mode uses the class strategy. Add dark to an ancestor such as <html> to switch the semantic tokens.

Recommended Theme Toggle Pattern

ngx-align-ui gives you the tokens and dark: variant support, but your app should own the theme state.

Recommended flow:

Store one of light, dark, or system in localStorage
Before Angular boots, resolve the real theme and toggle document.documentElement.classList
If the saved mode is system, follow prefers-color-scheme
Build layout wrappers with semantic utilities such as bg-bg-white-0, text-text-sub-600, and border-stroke-soft-200

Minimal bootstrap script for src/index.html:

<script>
  (() => {
    const mode = localStorage.getItem('ngx-align-ui-theme-mode') ?? 'system';
    const resolvedTheme =
      mode === 'system'
        ? window.matchMedia('(prefers-color-scheme: dark)').matches
          ? 'dark'
          : 'light'
        : mode;

    document.documentElement.classList.toggle('dark', resolvedTheme === 'dark');
    document.documentElement.style.colorScheme = resolvedTheme;
  })();
</script>

Angular bootstrap pattern:

import {
  ApplicationConfig,
  Injectable,
  inject,
  provideEnvironmentInitializer,
  signal,
} from '@angular/core';
import { provideRouter } from '@angular/router';

@Injectable({ providedIn: 'root' })
export class ThemeService {
  readonly mode = signal<'light' | 'dark' | 'system'>('system');

  setMode(mode: 'light' | 'dark' | 'system'): void {
    this.mode.set(mode);
    localStorage.setItem('ngx-align-ui-theme-mode', mode);

    const resolvedTheme =
      mode === 'system'
        ? window.matchMedia('(prefers-color-scheme: dark)').matches
          ? 'dark'
          : 'light'
        : mode;

    document.documentElement.classList.toggle('dark', resolvedTheme === 'dark');
    document.documentElement.style.colorScheme = resolvedTheme;
  }
}

export const appConfig: ApplicationConfig = {
  providers: [
    provideEnvironmentInitializer(() => {
      inject(ThemeService);
    }),
    provideRouter(routes),
  ],
};

Any header, settings drawer, or profile menu can then inject ThemeService and call setMode('light' | 'dark' | 'system').

Option B: Project Without Tailwind

If your project does not compile Tailwind, import the prebuilt stylesheet instead:

@import 'ngx-align-ui/styles.css';

This gives you the compiled utilities, component styles, and tokens in one file.

Quick Start

Most exports are standalone Angular components, so you can import them directly into a feature component.

import { Component } from '@angular/core';
import {
  ButtonComponent,
  CardBodyComponent,
  CardComponent,
  CardHeaderComponent,
} from 'ngx-align-ui';

@Component({
  selector: 'app-demo',
  standalone: true,
  imports: [ButtonComponent, CardBodyComponent, CardComponent, CardHeaderComponent],
  template: `
    <div class="max-w-md">
      <ngx-aui-card>
        <ngx-aui-card-header> Workspace setup </ngx-aui-card-header>

        <ngx-aui-card-body>
          <p class="text-paragraph-sm text-text-sub-600">
            Configure your project and continue with the migration flow.
          </p>

          <div class="mt-4 flex gap-3">
            <ngx-aui-button> Continue </ngx-aui-button>

            <ngx-aui-button variant="neutral" mode="stroke"> Cancel </ngx-aui-button>
          </div>
        </ngx-aui-card-body>
      </ngx-aui-card>
    </div>
  `,
})
export class DemoComponent {}

Utility Helpers

The package also exposes the same utility layer used internally by the components.

`cn`

Use cn to safely merge conditional class strings with AlignUI-aware Tailwind conflict resolution.

import { cn } from 'ngx-align-ui';

const classes = cn(
  'rounded-10 px-3 text-label-sm shadow-regular-sm',
  isCompact && 'px-2',
  isProminent && 'rounded-20 text-label-md shadow-regular-md',
);

`tv`

Use tv to define reusable variants with the same merge rules.

import { tv, type VariantProps } from 'ngx-align-ui';

export const badgeVariants = tv({
  base: 'inline-flex items-center rounded-20 text-label-xs',
  variants: {
    tone: {
      info: 'bg-information-lighter text-information-dark',
      success: 'bg-success-lighter text-success-dark',
    },
  },
  defaultVariants: {
    tone: 'info',
  },
});

export type BadgeVariants = VariantProps<typeof badgeVariants>;

Exported Design Tokens

You can also consume AlignUI tokens and config directly in TypeScript:

import { borderRadii, colors, shadows, texts, tailwindConfig } from 'ngx-align-ui';

Useful when building custom wrappers, Storybook examples, or project-specific extensions.

Component Coverage

The library currently includes a broad set of Angular ports for AlignUI primitives and components.

Actions: button, button-group, compact-button, fancy-button, link-button, social-button
Data display: avatar, badge, banner, card, divider, file-format-icon, hint, icon, kbd, status-badge, table, tag
Feedback: alert, notification, progress-bar, progress-circle, toast
Forms: checkbox, color-picker, datepicker, digit-input, file-upload, input, label, radio, select, slider, switch, textarea
Navigation and overlays: accordion, breadcrumb, command-menu, dot-stepper, dropdown, drawer, horizontal-stepper, modal, pagination, popover, segmented-control, tab-menu-horizontal, tab-menu-vertical, vertical-stepper

Local Development

From the workspace root:

npm install
npm run build:lib
npm run build:doc
ng serve ngx-align-ui-doc

Useful scripts:

npm run build:lib builds the Angular library, generates the compiled stylesheet, and patches CSS exports in dist/ngx-align-ui
npm run build:doc builds the documentation app
npm test runs Angular tests for the workspace
npm run lint runs ESLint

The workspace also contains a local documentation app under projects/ngx-align-ui-doc for validating component behavior and usage examples.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ngx-align-ui

What This Package Includes

Requirements

Installation

Styling Setup

Option A: Tailwind CSS v4 Project

Recommended Theme Toggle Pattern

Option B: Project Without Tailwind

Quick Start

Utility Helpers

cn

tv

Exported Design Tokens

Component Coverage

Local Development

`cn`

`tv`