Docs

Main site

Installation Browser support Extend config MCP server
Validation Page speed testing Responsive design
Accordion Aspect Ratio Avatar Badge Banner Bento Grid Blockquote Breadcrumbs Button Callout Card Drawer Dropdown Link Modal Navbar Navblock Pagination Popover Progress Separator Tabs Timeline Toast Tooltip
Checkbox Datepicker File upload Form field Input Label OTP Radio Range Select Textarea Toggle
Header Footer
Accordion Auth Checkbox & Radio Content Drawers Features Modals Statistics & Metrics Teams
Address Contact number Currency symbol Date Emirates ID Name
Close
Home Documentation Installation Using with Angular

Using with Angular

The UAE Design System ships generated Angular wrappers for every component — standalone components with typed inputs, typed outputs and OnPush change detection.

Introduction

Two packages, both required:

Package Role
@aegov/designsystem The web components — implementations, CSS and TypeScript types. Required at runtime.
@aegov/designsystem-angular Generated standalone component wrappers, the DIRECTIVES array and DesignSystemModule, plus provideDesignSystem() from the @aegov/designsystem-angular/provider entry point.

Declared peer dependencies are @angular/core and @angular/common at 18.0.0 or newer. On Angular 18, add standalone: true to every component that uses imports — the samples on this page leave it out because it is the default from Angular 19.

import { Component } from '@angular/core';
import { AegovButton } from '@aegov/designsystem-angular';

@Component({
  selector: 'app-root',
  imports: [AegovButton],
  template: `
    <aegov-button variant="primary" (aegovButtonClick)="submit()">
      Submit application
    </aegov-button>
  `,
})
export class App {
  submit() { /* … */ }
}

Step 1 — Install

npm install @aegov/designsystem @aegov/designsystem-angular

Step 2 — Set up Tailwind

The design system ships source CSS, so Tailwind v4 must run in your build.

If you selected Tailwind during ng new

The CLI already installed @tailwindcss/postcss, created .postcssrc.json, and put @import "tailwindcss" in src/styles.css. Add the design system lines after it:

/* src/styles.css */
@import "tailwindcss";
@source "./**/*.{ts,html}";
@import "@aegov/designsystem/base";
@import "@aegov/designsystem/theme";

If you did not select Tailwind during ng new

npm install -D tailwindcss @tailwindcss/postcss postcss

On Angular 18 (which has no Tailwind option in ng new), add --legacy-peer-deps to that command: the Angular 18 build tools declare an optional peer dependency on Tailwind v3, and npm otherwise refuses Tailwind v4 or leaves it where the build can't find it (Can't resolve 'tailwindcss'). The build then warns that some rules were skipped due to selector errors (the right-to-left rules); that warning is harmless — right-to-left styles still work.

Create .postcssrc.json at the project root — the Angular CLI picks it up automatically (postcss.config.json works too):

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

Then add all four lines to src/styles.css as shown above.

About @source: Tailwind v4 discovers the utility classes you use by scanning your project files, and in a standard Angular CLI project it already finds your .html templates and inline template: strings on its own. The @source "./**/*.{ts,html}" line is optional — it makes the scan explicit, which helps if your templates live outside the project root or a utility class is not being generated.

Import order matters: Tailwind first, then base, then theme.

Step 3 — Initialise the design system

Each wrapper registers its own aegov-* element as soon as you import it, so the components you import in Step 4 work on their own. Add provideDesignSystem() as well: it runs the design system's global setup at startup — for example, it creates the screen-reader live region that toasts announce into, so the first announcement is not missed — and makes every aegov-* tag available, loading each component's code only when that tag first appears on the page. It comes from its own entry point, @aegov/designsystem-angular/provider. It leaves your initial bundle the same size: when the app starts, it downloads the design system's loader as a separate file of about 90 kB (about 19 kB compressed). An app that doesn't use it ships none of the loader's files.

Standalone applications

Add the import and the provider to your existing app.config.ts. Keep the providers that are already there, such as provideRouter(), provideBrowserGlobalErrorListeners() and, in SSR apps, provideClientHydration().

// src/app/app.config.ts
import { provideDesignSystem } from '@aegov/designsystem-angular/provider';

export const appConfig: ApplicationConfig = {
  providers: [
    // …your existing providers
    provideDesignSystem(),
  ],
};

Module-based applications

Add DesignSystemModule to the imports of your existing root module, and provideDesignSystem() to its providers. Keep everything else in it, such as AppRoutingModule and the generated providers.

// src/app/app-module.ts (app.module.ts in Angular 19 and earlier)
import { DesignSystemModule } from '@aegov/designsystem-angular';
import { provideDesignSystem } from '@aegov/designsystem-angular/provider';

@NgModule({
  // …your existing declarations and bootstrap
  imports: [
    // …your existing imports, such as BrowserModule and AppRoutingModule
    DesignSystemModule,
  ],
  providers: [
    // …your existing providers
    provideDesignSystem(),
  ],
})
export class AppModule {}

DesignSystemModule re-exports every wrapper, so components declared in that module can use any aegov-* tag without further imports. It has no providers of its own: the global setup comes from provideDesignSystem().

Step 4 — Import the components you use

Every tag has a standalone wrapper named Aegov + PascalCase.

Tag Import
<aegov-button> AegovButton
<aegov-input> AegovInput
<aegov-select> AegovSelect
<aegov-form-field> AegovFormField
<aegov-header-banner> AegovHeaderBanner

Option A — individual imports (recommended)

Each component lists exactly the wrappers it uses, and only those components end up in your bundle:

import { Component } from '@angular/core';
import { AegovFormField, AegovLabel, AegovInput, AegovButton } from '@aegov/designsystem-angular';

@Component({
  selector: 'app-contact-step',
  imports: [AegovFormField, AegovLabel, AegovInput, AegovButton],
  template: `
    <aegov-form-field>
      <aegov-label>Email address</aegov-label>
      <aegov-input fieldId="email" type="email" placeholder="name@example.ae" />
    </aegov-form-field>

    <aegov-button variant="primary" size="lg">Continue</aegov-button>
  `,
})
export class ContactStepComponent {}

Option B — every component in one import

Import DesignSystemModule to make every aegov-* tag available in that component's template, without listing each wrapper:

import { Component } from '@angular/core';
import { DesignSystemModule } from '@aegov/designsystem-angular';

@Component({
  selector: 'app-contact-step',
  imports: [DesignSystemModule],
  template: `
    <aegov-form-field>
      <aegov-label>Email address</aegov-label>
      <aegov-input fieldId="email" type="email" placeholder="name@example.ae" />
    </aegov-form-field>

    <aegov-button variant="primary" size="lg">Continue</aegov-button>
  `,
})
export class ContactStepComponent {}

Only the components you actually use in your templates end up in the bundle, so Option B costs about the same as Option A. Like the individual wrappers, DesignSystemModule does not run the global setup — that comes from provideDesignSystem() in Step 3. Add DesignSystemModule to the imports of every component that uses aegov-* tags — importing it in one component does not make the tags available in others.

You still import a wrapper class when your TypeScript code refers to it directly, for example as a viewChild type. It does not need to go in the imports array.

Always use the HTML tag in templates (<aegov-button>), never the class name.

Inputs — camelCase in templates

This is the main difference from plain HTML and Vue. Angular's template compiler resolves inputs by their declared name, and the generated wrappers declare them in camelCase.

<!-- Plain HTML / Vue -->
<aegov-input field-id="email" is-required />

<!-- Angular -->
<aegov-input fieldId="email" [isRequired]="true" />
HTML attribute Angular input
field-id fieldId
is-disabled isDisabled
is-required isRequired
is-invalid isInvalid
error-message errorMessage
default-open defaultOpen
page-current pageCurrent

Inputs are type-checked under strictTemplates, which ng new turns on by default. Boolean and number inputs also accept static attributes and convert them to the real value: isRequired and isRequired="true" give true, isDisabled="false" gives false, and pages="5" gives 5. Bind variables and expressions with square brackets:

<aegov-input isRequired [isDisabled]="form.locked" />
<aegov-pagination pages="5" [pageCurrent]="page" />
<aegov-pagination [pages]="totalPages" [pageCurrent]="page" />
<aegov-button size="sm md:base xl:lg">Responsive size string</aegov-button>

A value of the wrong type is a compile-time error, for example pages="five", [pages]="'five'" or variant="primry". So is a string variable bound to an input that takes a fixed set of values, such as variant: give the variable the design system's type instead, for example variant: ButtonVariant = 'primary' (see TypeScript below). Only boolean and number inputs convert static attributes, so a bare status on aegov-avatar, which takes true, false or a status name, is an error too — write [status]="true" or status="online".

Required inputs

Four inputs are marked required by their components. Omitting one — or spelling it in kebab-case — is a compile-time error, NG8008.

Component Required input
aegov-tab tabId
aegov-tab-panel tabId
aegov-link href
aegov-radio-group name
<!-- NG8008: Required input 'tabId' from component AegovTab must be specified. -->
<aegov-tabs defaultOpen="overview">
  <aegov-tab slot="tabs" tab-id="overview">Overview</aegov-tab>
</aegov-tabs>

<!-- Correct -->
<aegov-tabs defaultOpen="overview">
  <aegov-tab slot="tabs" tabId="overview">Overview</aegov-tab>
  <aegov-tab-panel tabId="overview">Service overview…</aegov-tab-panel>
</aegov-tabs>

aegov-tab and aegov-tab-panel must always sit inside aegov-tabs — on their own they log an error at runtime.

Outputs — (aegovEvent) syntax

Component events are declared as Angular outputs, keeping the original event name. The $event you receive is the CustomEvent, so the payload is on $event.detail.

<aegov-button (aegovButtonClick)="submit($event)">Submit</aegov-button>

<aegov-input
  (aegovInputChange)="email = $event.detail.value"
  (aegovInputBlur)="touched = true"
/>

<aegov-select (aegovSelectChange)="onEmirate($event)" />

<aegov-badge [isDismissible]="true" (aegovBadgeDismiss)="removeFilter(id)" />

Template refs and imperative methods

Query the wrapper class with viewChild to get a typed reference to the component, then call its methods on it. Methods are async.

import { Component, viewChild } from '@angular/core';
import { AegovModal, AegovButton } from '@aegov/designsystem-angular';

@Component({
  selector: 'app-confirm',
  imports: [AegovModal, AegovButton],
  template: `
    <aegov-button (aegovButtonClick)="open()">Review submission</aegov-button>

    <aegov-modal label="Confirm submission">
      <p>Submit your application for review?</p>
      <aegov-button variant="primary" (aegovButtonClick)="close()">Confirm</aegov-button>
    </aegov-modal>
  `,
})
export class ConfirmComponent {
  private modal = viewChild.required(AegovModal);

  async open() { await this.modal().show(); }
  async close() { await this.modal().close(); }
}

To reach the underlying custom element instead, add a template reference (#modal) and query it with read: ElementRef: viewChild.required<string, ElementRef<HTMLAegovModalElement>>('modal', { read: ElementRef }).

Form binding

The components are web components with their own internal value, and they participate in native form submission. They are not yet wired into Angular's forms API.

What works today

Bind the value in, listen for changes out:

import { Component, signal } from '@angular/core';
import { AegovFormField, AegovLabel, AegovInput, AegovButton } from '@aegov/designsystem-angular';

@Component({
  selector: 'app-application-form',
  imports: [AegovFormField, AegovLabel, AegovInput, AegovButton],
  template: `
    <form (submit)="onSubmit($event)">
      <aegov-form-field>
        <aegov-label>Emirates ID</aegov-label>
        <aegov-input
          fieldId="emirates-id"
          name="emiratesId"
          [isRequired]="true"
          [value]="emiratesId()"
          (aegovInputChange)="emiratesId.set($event.detail.value)"
        />
      </aegov-form-field>

      <aegov-button type="submit" variant="primary" [isLoading]="isSubmitting()">
        Submit application
      </aegov-button>
    </form>
  `,
})
export class ApplicationFormComponent {
  emiratesId = signal('');
  isSubmitting = signal(false);

  async onSubmit(e: Event) {
    e.preventDefault();
    const data = new FormData(e.target as HTMLFormElement);
    this.isSubmitting.set(true);
    try {
      // Replace with your own API call.
      await fetch('/api/applications', { method: 'POST', body: data });
    } finally {
      this.isSubmitting.set(false);
    }
  }
}

Submit buttons

An aegov-button with type="submit" submits its form like a native submit button. Give it name and value to tell several submit buttons apart: event.submitter is a hidden native button that stands in for the aegov-button and carries its name and value, so new FormData(form, event.submitter) includes the pair, as does a form the browser submits itself. Attributes such as formnovalidate and formaction on the aegov-button apply to that submission.

import { Component } from '@angular/core';
import { AegovInput, AegovButton } from '@aegov/designsystem-angular';

@Component({
  selector: 'app-save-or-submit',
  imports: [AegovInput, AegovButton],
  template: `
    <form (submit)="onSubmit($event)">
      <aegov-input fieldId="full-name" name="fullName" [isRequired]="true" />

      <aegov-button type="submit" name="intent" value="draft" appearance="outline" formnovalidate>
        Save draft
      </aegov-button>
      <aegov-button type="submit" name="intent" value="submit">
        Submit application
      </aegov-button>
    </form>
  `,
})
export class SaveOrSubmitComponent {
  onSubmit(e: SubmitEvent) {
    e.preventDefault();
    const data = new FormData(e.target as HTMLFormElement, e.submitter);
    console.log(data.get('intent')); // 'draft' or 'submit'
  }
}

What is not supported yet

[(ngModel)] and formControlName do not work with aegov-* components — using them throws NG01203: No value accessor for form control. There is no ControlValueAccessor bridge in the current release. Use the value-in / event-out pattern above, or wrap a component in your own thin Angular component that implements ControlValueAccessor if you need Reactive Forms integration in the meantime.

TypeScript

import type {
  ButtonVariant,
  SelectChangeDetail,
  AegovValidationDetail,
  Components,
} from '@aegov/designsystem';

const variant: ButtonVariant = 'primary';
const size: Components.AegovInput['size'] = 'lg';

function onValidate(e: CustomEvent<AegovValidationDetail<string>>) {
  console.log(e.detail.value, e.detail.validity, e.detail.trigger);
}

RTL support

Set dir on the document or a subtree. The components use logical properties throughout, and the base stylesheet switches the body and heading font stacks to Noto Kufi Arabic and Alexandria automatically.

import { Component, signal } from '@angular/core';
import { RouterOutlet } from '@angular/router';

@Component({
  selector: 'app-shell',
  imports: [RouterOutlet],
  template: `
    <div [attr.dir]="locale() === 'ar' ? 'rtl' : 'ltr'" [attr.lang]="locale()">
      <router-outlet />
    </div>
  `,
})
export class ShellComponent {
  locale = signal<'en' | 'ar'>('en');
}

Server-side rendering

Custom elements only run in the browser. On the server, aegov-* tags render as plain elements and upgrade once the page loads in the browser. Guard any code that calls component methods with a platform check. Call inject(PLATFORM_ID) in a field initialiser — inject() cannot be called inside a method.

import { Component, PLATFORM_ID, inject, viewChild } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import { AegovButton, AegovModal } from '@aegov/designsystem-angular';

@Component({
  selector: 'app-confirm',
  imports: [AegovButton, AegovModal],
  template: `
    <aegov-button (aegovButtonClick)="open()">Review submission</aegov-button>
    <aegov-modal label="Confirm submission">…</aegov-modal>
  `,
})
export class ConfirmComponent {
  private isBrowser = isPlatformBrowser(inject(PLATFORM_ID));
  private modal = viewChild.required(AegovModal);

  async open() {
    if (this.isBrowser) {
      await this.modal().show();
    }
  }
}

Hydration

With client hydration enabled (provideClientHydration(), the default for ng new --ssr), some components — such as aegov-form-field and aegov-label — adjust their markup in the browser before Angular hydrates the page. Angular then reports NG0500: During hydration Angular expected … but found a comment node, and event bindings on the page stop working. Add ngSkipHydration to the host element of every component whose template uses aegov-* elements:

<app-contact-step ngSkipHydration />
<app-confirm ngSkipHydration />

Those components are then rendered fresh in the browser instead of hydrated; the rest of the page still hydrates normally.

The global stylesheet is SSR-safe and should stay in src/styles.css so the server-rendered markup is styled on first paint.

Validation

Form components ship the validation surface: isInvalid, errorMessage and hint inputs, error and hint slots, the aegovValidate output, and validate() / setCustomValidity() methods.

import { Component, signal } from '@angular/core';
import { AegovInput } from '@aegov/designsystem-angular';
import type { AegovValidationDetail } from '@aegov/designsystem';

@Component({
  selector: 'app-email-field',
  imports: [AegovInput],
  template: `
    <aegov-input
      name="email"
      type="email"
      [isInvalid]="!!error()"
      [errorMessage]="error()"
      (aegovValidate)="onValidate($event)"
    />
  `,
})
export class EmailFieldComponent {
  error = signal('');

  onValidate(e: CustomEvent<AegovValidationDetail<string>>) {
    if (e.detail.trigger !== 'blur') return;
    const ok = /\S+@\S+\.\S+/.test(String(e.detail.value));
    this.error.set(ok ? '' : 'Enter a valid email address');
  }
}

Troubleshooting

Check, in order: 1) src/styles.css contains @import "tailwindcss", then base, then theme, in that order (the @source line is optional); 2) .postcssrc.json (or postcss.config.json) exists at the project root; 3) DevTools → Elements → :root lists --color-primary-600. You wrote tab-id instead of tabId. Angular resolves inputs by camelCase name. Same applies to href on aegov-link and name on aegov-radio-group. Import provideDesignSystem from @aegov/designsystem-angular/provider, not from the main package entry point. Neither the wrapper (AegovButton) nor DesignSystemModule is in that component's imports array, or, in a module-based app, the module does not import DesignSystemModule. The tag is in a template but nothing registered it. Import its wrapper (or DesignSystemModule) into that component's imports. If you use CUSTOM_ELEMENTS_SCHEMA with plain tags instead of wrappers, make sure provideDesignSystem() is in your app config. Tailwind did not scan the file. Add or widen the @source glob in src/styles.css. You used [(ngModel)] or formControlName on an aegov-* component — see Form binding above. In a production build the same mistake shows as TypeError: Cannot read properties of null (reading 'writeValue') instead. Use value-in / event-out, or write your own ControlValueAccessor wrapper.

Where to next

Using with React Using with Vue Back to Installation