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.
@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
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.
tab-id instead of tabId. Angular resolves inputs by camelCase name. Same applies to href on aegov-link and name on aegov-radio-group.
provideDesignSystem from @aegov/designsystem-angular/provider, not from the main package entry point.
AegovButton) nor DesignSystemModule is in that component's imports array, or, in a module-based app, the module does not import DesignSystemModule.
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.
@source glob in src/styles.css.
[(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.