Introduction
There are two packages, and you need both:
| Package | Role |
|---|---|
@aegov/designsystem |
The web components — implementations, CSS and TypeScript types. Required at runtime. |
@aegov/designsystem-react |
Thin React wrappers plus types. Importing a wrapper registers that component's custom element. In a production build only the ones you import are registered and bundled; dev servers that don't tree-shake register them all. |
Because the wrappers register their own elements, you never call defineCustomElements() in a React app. Importing AegovButton is enough to define <aegov-button>.
import { AegovButton } from '@aegov/designsystem-react';
export default function App() {
return (
<AegovButton variant="primary" onAegovButtonClick={() => console.log('clicked')}>
Submit application
</AegovButton>
);
}
Step 1 — Install
npm install @aegov/designsystem @aegov/designsystem-react
React 18 or 19 is required. The wrappers are built on @stencil/react-output-target, which supports only those two versions; React 17 and older are not supported.
Step 2 — Set up Tailwind and the stylesheet
The design system ships source CSS, so your project must run Tailwind v4. For Vite:
npm install -D tailwindcss @tailwindcss/vite
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({
plugins: [react(), tailwindcss()],
});
Create the stylesheet — Tailwind first, then base (fonts, resets, global element styles), then theme (design tokens):
/* src/styles.css */
@import "tailwindcss";
@import "@aegov/designsystem/base";
@import "@aegov/designsystem/theme";
Import it once from your entry file:
// src/main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './styles.css';
import App from './App';
createRoot(document.getElementById('root')!).render(
<StrictMode>
<App />
</StrictMode>,
);
The Vite React template also creates src/index.css and src/App.css, and their styles override the design system's. Delete both files, and remove the import './App.css' line from src/App.tsx.
Using Next.js? See Server-side rendering and Next.js below for its stylesheet setup. For Webpack or other PostCSS-based setups, see Installation; with Webpack, React also needs a JSX loader, for example babel-loader with @babel/preset-react set to { runtime: 'automatic' }.
Step 3 — Use a component
Every tag has a wrapper named Aegov + PascalCase:
| Tag | Import |
|---|---|
<aegov-button> |
AegovButton |
<aegov-input> |
AegovInput |
<aegov-form-field> |
AegovFormField |
<aegov-select-option> |
AegovSelectOption |
<aegov-header-banner> |
AegovHeaderBanner |
import { AegovFormField, AegovLabel, AegovInput, AegovButton } from '@aegov/designsystem-react';
export function ContactStep() {
return (
<div className="max-w-md">
<AegovFormField>
<AegovLabel>Email address</AegovLabel>
<AegovInput fieldId="email" type="email" placeholder="name@example.ae" />
</AegovFormField>
<AegovButton variant="primary" size="lg" className="mt-4">
Continue
</AegovButton>
</div>
);
}
Each wrapper does four things: registers its custom element when you import it, renders the underlying tag, forwards props to DOM properties, and adapts the component's CustomEvents into React handler props.
If your app server-renders (Next.js, Remix, or similar), see Server-side rendering and Next.js before using this example.
Props — camelCase, not kebab-case
Plain HTML uses kebab-case attributes. The React wrappers expose the camelCase property names instead.
{/* Recommended — typed props */}
<AegovInput fieldId="email" isRequired isDisabled={false} />
{/* Works, but avoid — bypasses the wrapper's typed props */}
<AegovInput field-id="email" is-required />
The kebab-case form compiles and works at runtime, because React passes unknown hyphenated names straight to the element as attributes. But TypeScript cannot check them — a typo such as is-requred fails silently — and you lose editor autocompletion, so prefer the camelCase props.
| HTML attribute | React prop |
|---|---|
field-id |
fieldId |
is-disabled |
isDisabled |
is-required |
isRequired |
is-invalid |
isInvalid |
error-message |
errorMessage |
default-open |
defaultOpen |
addon-prefix |
addonPrefix |
label-nav |
labelNav |
Booleans
Pass real booleans — the prop types are boolean, so TypeScript rejects a string value at compile time:
<AegovButton isDisabled>Disabled</AegovButton>
<AegovButton isDisabled={true}>Disabled</AegovButton>
<AegovButton isDisabled={isSubmitting}>Conditional</AegovButton>
className, not class
JSX conventions apply; the wrapper forwards className to the host element correctly.
<AegovButton className="mt-4 w-full sm:w-auto">Submit</AegovButton>
Components that expose an extraClass property accept it as a prop too — that one targets an inner element rather than the host, and each component page documents which.
Responsive size strings
size still takes the responsive string form; it is just a string prop.
<AegovButton size="sm md:base xl:lg">Adapts to the viewport</AegovButton>
Events — onAegov* handlers
Component events arrive as camelCased props with an onAegov prefix, typed as CustomEvent handlers. Read the payload from event.detail.
<AegovInput
name="emiratesId"
onAegovInputValue={(e) => setDraft(e.detail.value)} // every keystroke
onAegovInputChange={(e) => setValue(e.detail.value)} // when the value is committed
onAegovInputBlur={() => setTouched(true)}
/>
<AegovSelect onAegovSelectChange={(e) => console.log(e.detail.value, e.detail.label)} />
<AegovBadge isDismissible onAegovBadgeDismiss={() => removeFilter(id)} />
Text fields have two value events, like the native input and change events:
| Handler | Fires |
|---|---|
onAegovInputValue / onAegovTextareaValue |
On every keystroke. Use it for live feedback, such as a character count or search-as-you-type. |
onAegovInputChange / onAegovTextareaChange |
When the value is committed — the field loses focus after a change, or (in an input) the user presses Enter. Use it when you only need the final value. |
Native React events still work where the DOM emits them — onClick, onFocus, onKeyDown — except inside an open popover or dropdown menu (see below). Prefer the onAegov* handler whenever one exists, because it carries structured detail that the native event does not.
Handlers inside popover and dropdown menus
aegov-popover and aegov-dropdown move their content to the end of document.body while they are open, so a menu can escape containers that clip it. React listens for events on your app's root element, so a plain onClick, onChange or onInput on anything inside popover-content or dropdown-content never fires. The onAegov* handlers are attached to the element itself, so they keep working:
<AegovDropdown>
<AegovButton>Actions</AegovButton>
<div slot="dropdown-content">
{/* onClick here would never fire while the menu is open */}
<AegovButton onAegovButtonClick={archive}>Archive</AegovButton>
</div>
</AegovDropdown>
For a native element in the menu, such as a <button>, bind the handler through a ref:
const archiveRef = useRef<HTMLButtonElement>(null);
useEffect(() => {
const button = archiveRef.current;
button?.addEventListener('click', archive);
return () => button?.removeEventListener('click', archive);
}, []);
// <button ref={archiveRef}>Archive</button>
Links with an href need no handler. Modals and drawers are not affected: they open where you declare them, inside your app, so onClick and every other React handler inside them work as usual. (They move only out of an ancestor that would hide or clip them, such as one with a transform or z-index, and stay inside your app unless that ancestor is your app's root element itself.)
Refs and imperative methods
ref gives you the underlying custom element, typed as HTMLAegov*Element. These types are declared globally by @aegov/designsystem — no import needed. Component methods are async.
import { useRef } from 'react';
import { AegovModal, AegovButton } from '@aegov/designsystem-react';
export function ConfirmDialog() {
const modal = useRef<HTMLAegovModalElement>(null);
return (
<>
<AegovButton onAegovButtonClick={() => modal.current?.show()}>
Review submission
</AegovButton>
<AegovModal ref={modal} label="Confirm submission">
<p>Submit your application for review?</p>
<AegovButton variant="primary" onAegovButtonClick={() => modal.current?.close()}>
Confirm
</AegovButton>
</AegovModal>
</>
);
}
For form components, validate() and setCustomValidity() are the two you will reach for most:
const input = useRef<HTMLAegovInputElement>(null);
const check = async () => {
const result = await input.current?.validate('manual');
if (!result?.valid) input.current?.focus();
};
Controlled and uncontrolled inputs
The components own their internal value, so they behave like uncontrolled inputs by default. Passing value sets the field's value — and changing your state later updates the field — but typing does not go through React, so keep your state in sync from the value event:
const [email, setEmail] = useState('');
<AegovInput
name="email"
type="email"
value={email}
onAegovInputValue={(e) => setEmail(e.detail.value)}
/>
Use onAegovInputChange instead if you only need the value once the user leaves the field.
For form submission you often do not need React state at all — the components participate in native <form> submission, so new FormData(form) returns everything:
function ApplicationForm() {
const onSubmit = (e: React.SyntheticEvent<HTMLFormElement>) => {
e.preventDefault();
const data = Object.fromEntries(new FormData(e.currentTarget));
api.submit(data);
};
return (
<form onSubmit={onSubmit}>
<AegovInput name="fullName" isRequired />
<AegovButton type="submit" variant="primary">Submit</AegovButton>
</form>
);
}
An AegovButton with type="submit" submits its form like a native submit button. Give it name and value to tell several submit buttons apart: event.nativeEvent.submitter is a hidden native button that stands in for the AegovButton and carries its name and value, so new FormData(form, submitter) includes the pair, as does a form the browser submits itself. The formnovalidate, formaction, formmethod, formenctype and formtarget attributes on the element apply to that submission too. They are not wrapper props, so set them through a ref — for example buttonRef.current?.setAttribute('formnovalidate', '').
function SaveOrSubmit() {
const onSubmit = (e: React.SyntheticEvent<HTMLFormElement, SubmitEvent>) => {
e.preventDefault();
const data = new FormData(e.currentTarget, e.nativeEvent.submitter);
console.log(data.get('intent')); // 'draft' or 'submit'
};
return (
<form onSubmit={onSubmit}>
<AegovInput name="fullName" />
<AegovButton type="submit" name="intent" value="draft" appearance="outline">
Save draft
</AegovButton>
<AegovButton type="submit" name="intent" value="submit">
Submit application
</AegovButton>
</form>
);
}
TypeScript
Component prop types come from the wrapper automatically. Shared payload and token types are exported from the core package:
import type {
ButtonVariant,
ButtonAppearance,
SelectChangeDetail,
AegovValidationDetail,
} from '@aegov/designsystem';
const variant: ButtonVariant = 'primary';
function onValidate(e: CustomEvent<AegovValidationDetail<string>>) {
console.log(e.detail.value, e.detail.validity, e.detail.trigger);
}
The HTMLAegov*Element types used for refs are declared globally rather than exported — reference them by name with no import.
RTL support
Direction is a DOM concern, so nothing React-specific is required — set dir on the document or on a subtree and the components flip, including the font stacks.
export function Layout({ locale, children }: { locale: 'en' | 'ar'; children: React.ReactNode }) {
return (
<div dir={locale === 'ar' ? 'rtl' : 'ltr'} lang={locale}>
{children}
</div>
);
}
If you toggle locale at runtime, set dir on document.documentElement. Toast renders into one global container that reads its direction from there, and dropdown, popover, datepicker, modal and drawer copy the direction of where they were declared when they open — so a component that is already open keeps its direction until it is opened again.
Server-side rendering and Next.js
Custom elements are a browser API. On the server, a component has no implementation to run yet — its real markup only exists once the browser loads and upgrades it.
'use client' alone does not avoid this, since most SSR frameworks still render client components once on the server by default.
The reliable option today is to load the components in the browser only. In Next.js that takes three files: the component, a small client-only loader for it, and the page that uses it.
// src/components/contact-step.tsx — the component from Step 3
import { AegovFormField, AegovLabel, AegovInput, AegovButton } from '@aegov/designsystem-react';
export function ContactStep() {
return (
<div className="max-w-md">
<AegovFormField>
<AegovLabel>Email address</AegovLabel>
<AegovInput fieldId="email" type="email" placeholder="name@example.ae" />
</AegovFormField>
<AegovButton variant="primary" size="lg" className="mt-4">
Continue
</AegovButton>
</div>
);
}
// src/components/contact-step-client.tsx
'use client';
import dynamic from 'next/dynamic';
// Loaded in the browser only, so it is never server-rendered or hydrated.
// `ssr: false` is only allowed inside a Client Component like this one.
export const ContactStep = dynamic(
() => import('./contact-step').then((m) => m.ContactStep),
{ ssr: false },
);
// src/app/page.tsx
import { ContactStep } from '@/components/contact-step-client';
export default function Page() {
return (
<main className="aegov-container py-10">
<h1>Contact details</h1>
<ContactStep />
</main>
);
}
The stylesheet is SSR-safe, so the page is styled from the first paint. A project created with create-next-app and Tailwind already runs Tailwind v4 (through @tailwindcss/turbopack in next.config.ts), and src/app/layout.tsx already imports ./globals.css. Replace the whole contents of src/app/globals.css with the three lines — the starter's own styles there would otherwise override the design system's body background and text colours, and switch them in dark mode through its --background and --foreground variables:
/* src/app/globals.css */
@import "tailwindcss";
@import "@aegov/designsystem/base";
@import "@aegov/designsystem/theme";
Without the src/ folder option, the same files live in app/ and components/.
Validation
Form components ship the validation surface: isInvalid, errorMessage and hint props, error and hint slots, an onAegovValidate handler, and validate() / setCustomValidity() methods.
const [error, setError] = useState('');
<AegovInput
name="email"
type="email"
isInvalid={!!error}
errorMessage={error}
onAegovValidate={(e) => {
if (e.detail.trigger !== 'blur') return;
const ok = /\S+@\S+\.\S+/.test(String(e.detail.value));
setError(ok ? '' : 'Enter a valid email address');
}}
/>
Common gotchas
<AegovButton> with <aegov-button> in the same codebase without knowing you lose typing and the onAegov* handlers on the latter.
aegov-button, aegov-modal, aegov-drawer, the header components, and every shadow-DOM form control use shadow DOM. React children are projected into slots as normal — but utility classes you put on children are styled by your app's CSS, not the component's.
document.body (modal and drawer only while they are open). React refs to the host still work, but document.querySelector inside a React container will not find the portalled content.