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 React

Using with React

The UAE Design System ships a typed React wrapper for every component — camelCase props, onAegov* event handlers, refs to the underlying element, and no customElements.define plumbing of your own.

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.

Current limitation: server-rendering design system components — in Next.js, Remix, or any other SSR framework — can currently produce a React hydration mismatch. This can affect any composition of more than a single component. '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

The wrappers register their own elements. Calling the loader as well is harmless but pointless, and pulls in the lazy-loading runtime you were avoiding by using the wrappers. In Angular and Vue templates you write the HTML tag. In React you write the wrapper — don't mix <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. Toast, dropdown, popover, datepicker, modal, and drawer move content into 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.

Where to next

Using with Vue Using with Angular Back to Installation