Introduction
Two packages, both required:
| Package | Role |
|---|---|
@aegov/designsystem |
The web components — implementations, CSS and TypeScript types. Required at runtime. |
@aegov/designsystem-vue |
The ComponentLibrary Vue plugin, defineDesignSystem(), and a generated typed component per tag. |
// src/main.ts
import { createApp } from 'vue';
import './style.css';
import App from './App.vue';
import { ComponentLibrary, defineDesignSystem } from '@aegov/designsystem-vue';
defineDesignSystem().then(() => {
createApp(App)
.use(ComponentLibrary)
.mount('#app');
});
<template>
<aegov-button variant="primary" @aegovButtonClick="submit">
Submit application
</aegov-button>
</template>
<script setup lang="ts">
function submit() {
// Send the application
}
</script>
The plugin registers every aegov-* element and runs the design system's global script (the toast live region and window.aegovToast), so every tag is available everywhere — no per-component import, no registration in individual .vue files.
Registration is asynchronous. defineDesignSystem() returns a promise that resolves once every element is registered; mounting after it resolves means the first render passes props to registered elements. In an entry file that supports top-level await, await defineDesignSystem(); before createApp() does the same.
Step 1 — Install
npm install @aegov/designsystem @aegov/designsystem-vue
Vue 3.5 or newer is what the package is built and tested against. Vue 2 is not supported.
Step 2 — Set up Tailwind and the stylesheet
The design system ships source CSS, so Tailwind v4 must run in your project.
npm install -D tailwindcss @tailwindcss/vite
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
// Tell Vue that aegov-* tags are custom elements, not Vue components.
isCustomElement: (tag) => tag.startsWith('aegov-'),
},
},
}),
tailwindcss(),
],
});
That isCustomElement line is required for the aegov-* tags (the typed components in Option B don't need it). Without it, Vue treats every aegov-* tag as a Vue component it can't find, and:
- every
@aegov…event listener silently never fires, so modals can't be opened from a button and validation handlers never run; v-modeldoes nothing;- in development, Vue logs
Failed to resolve component: aegov-buttonfor each tag.
Replace the contents of the template's src/style.css — Tailwind first, then base, then theme:
/* src/style.css */
@import "tailwindcss";
@import "@aegov/designsystem/base";
@import "@aegov/designsystem/theme";
Import it in your entry file before registering the plugin, as shown in the Introduction.
Step 3 — Use a component
Option A — custom element tags (recommended)
Write the HTML tag. Attributes are kebab-case, exactly as in plain HTML.
<template>
<div class="max-w-md">
<aegov-form-field>
<aegov-label>Email address</aegov-label>
<aegov-input field-id="email" type="email" placeholder="name@example.ae" />
</aegov-form-field>
<aegov-button variant="primary" size="lg" class="mt-4">Continue</aegov-button>
</div>
</template>
The tags match the HTML in every component's examples, and they are what you use with Nuxt and server-side rendering.
Option B — typed components
The package also exports a typed component per tag, named Aegov + PascalCase (AegovButton, AegovInput, …). Each one registers its own element, so it needs neither the plugin nor isCustomElement, and its props reach the component on the first render. vue-tsc type-checks props and events. As with the tags, listen for events by their camelCase name.
<template>
<AegovInput fieldId="email" type="email" name="email" v-model="email" />
<AegovCheckbox fieldId="terms" name="terms" label="I accept the terms" v-model="accepted" />
<AegovButton variant="primary" size="lg" @aegovButtonClick="submit">
Submit application
</AegovButton>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { AegovButton, AegovCheckbox, AegovInput } from '@aegov/designsystem-vue';
const email = ref('');
const accepted = ref(false);
function submit() {
// Send the application
}
</script>
If you use typed components without installing the plugin:
- Tags you nest inside them must be typed components too —
AegovTabandAegovTabPanelinsideAegovTabs,AegovLabelinsideAegovFormField, not<aegov-tab>or<aegov-label>. Only the plugin or the matching typed component registers an element. The development server registers every element up front, so a plain nested tag can look fine until you build for production, where it stays an unknown, unstyled element. - There is no toast live region, and
window.aegovToast.show()fails becauseaegov-toastis never registered. Addapp.use(ComponentLibrary)if you use toasts.
Props and attributes
In templates, prefer kebab-case attributes. For anything that is not a plain string, bind it so Vue passes a real value rather than a string:
<template>
<!-- Strings — plain attributes are fine -->
<aegov-input field-id="email" type="email" placeholder="Enter your email" />
<!-- Booleans and numbers — bind them -->
<aegov-input :is-required="true" :is-disabled="isLocked" />
<aegov-pagination :pages="totalPages" :page-current="page" />
<!-- Responsive size string -->
<aegov-button size="sm md:base xl:lg">Adapts to the viewport</aegov-button>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const isLocked = ref(false);
const totalPages = ref(10);
const page = ref(1);
</script>
Booleans
Static boolean attributes work as in HTML: is-required and is-required="true" turn the flag on, is-required="false" turns it off. When the value comes from your component state, bind it:
<aegov-input is-required />
<aegov-input :is-required="isFieldRequired" />
Use kebab-case, not camelCase
Write attributes in kebab-case on aegov-* tags, whether static or bound. Vue sets a camelCase name such as tabId as a property only if the component is already registered. Otherwise it falls back to an attribute, the browser lowercases it to tabid, and the component never receives it — the tab doesn't pair with its panel.
If you mount without waiting for defineDesignSystem(), registration finishes after mount(), so camelCase attributes are lost on the first render while tags rendered later work, which makes the problem intermittent. The development server registers every element up front, so it can hide the problem until a production build. Waiting for defineDesignSystem() before mount(), as in the Introduction, fixes it. tab-id="one" and :tab-id="id" work either way.
Events
Components emit native CustomEvents, dispatched under their camelCase property name exactly as declared in source (Stencil does not kebab-case event names). In templates, listen with that same camelCase name after @ — not kebab-case. The payload is on event.detail.
@/v-on binding on a plain custom element tag (not a Vue component) attaches a listener for the literal string you write. Vue has a deliberate escape hatch for this: if the name after @ contains any uppercase letter, Vue preserves it exactly; an all-lowercase, hyphenated name instead goes through Vue's default camelize→hyphenate round-trip and ends up registered as that same hyphenated string — which no aegov-* component ever dispatches. So @aegovBadgeDismiss works, and @aegov-badge-dismiss silently never fires — no console error, no warning, just a listener that's never called.
<template>
<aegov-input @aegovInputChange="onChange" @aegovInputBlur="touched = true" />
<aegov-select
appearance="listbox"
@aegovSelectChange="onSelectChange"
@aegovSelectOpen="isOpen = true"
@aegovSelectClose="isOpen = false"
>
<aegov-select-option value="dubai">Dubai</aegov-select-option>
<aegov-select-option value="abu-dhabi">Abu Dhabi</aegov-select-option>
</aegov-select>
<aegov-badge v-if="showFilter" is-dismissible @aegovBadgeDismiss="showFilter = false">Dubai</aegov-badge>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import type { SelectChangeDetail } from '@aegov/designsystem';
const touched = ref(false);
const isOpen = ref(false);
const showFilter = ref(true);
function onChange(e: CustomEvent<{ value: string; event: Event }>) {
console.log(e.detail.value);
}
function onSelectChange(e: CustomEvent<SelectChangeDetail>) {
console.log(e.detail.value, e.detail.label);
}
</script>
@aegovSelectOpen and @aegovSelectClose fire only with appearance="listbox". The default appearance uses the browser's native select, which has no open or close event.
The template listener name is identical to the event name: aegovInputChange is @aegovInputChange, aegovDatepickerMonthChange is @aegovDatepickerMonthChange — no case conversion.
v-model
Typed components
On the typed components, v-model binds value on AegovInput, AegovTextarea, AegovSelect, AegovOtp, AegovRange and AegovDatepicker, and isChecked on AegovCheckbox and AegovToggle. It updates as the user changes the field, and setting the ref updates the field.
For radios, wrap AegovRadio in AegovRadioGroup and listen for @aegovRadioGroupChange instead of using v-model — a radio that is unchecked because another one was selected doesn't update its own v-model.
<template>
<AegovSelect fieldId="district" v-model="district">
<AegovSelectOption value="dubai">Dubai</AegovSelectOption>
<AegovSelectOption value="abu-dhabi">Abu Dhabi</AegovSelectOption>
</AegovSelect>
<AegovToggle fieldId="alerts" label="Email me updates" v-model="wantsAlerts" />
<AegovRadioGroup
name="delivery"
label="Delivery"
@aegovRadioGroupChange="delivery = $event.detail.value ?? ''"
>
<AegovRadio fieldId="delivery-standard" value="standard" label="Standard delivery" :isChecked="delivery === 'standard'" />
<AegovRadio fieldId="delivery-express" value="express" label="Express delivery" :isChecked="delivery === 'express'" />
</AegovRadioGroup>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { AegovRadio, AegovRadioGroup, AegovSelect, AegovSelectOption, AegovToggle } from '@aegov/designsystem-vue';
const district = ref('');
const wantsAlerts = ref(false);
const delivery = ref('standard');
</script>
Custom element tags
v-model works on the aegov-input and aegov-textarea tags (with isCustomElement set, as in Step 2). It updates as the user types, and setting the ref updates the field:
<template>
<aegov-input field-id="email" type="email" v-model="email" />
<aegov-textarea field-id="notes" v-model="notes" />
</template>
<script setup lang="ts">
import { ref } from 'vue';
const email = ref('');
const notes = ref('');
</script>
Don't combine v-model with an @aegovInputValue or @aegovTextareaValue handler that changes rendered state — in Chrome, Edge and Safari the field resets on every keystroke. If you need to react to each keystroke, use :value with @aegovInputValue (shown below) instead of v-model.
With server-side rendering (Nuxt), don't use v-model on aegov-* tags — Vue's server compiler rejects it and the build fails with v-model can only be used on <input>, <textarea> and <select> elements. Bind the value and listen for the per-keystroke event instead:
<aegov-input field-id="email" type="email" :value="email" @aegovInputValue="email = $event.detail.value" />
Don't use v-model on the other form tags (select, checkbox, radio, toggle, datepicker and the rest) — it breaks them. On aegov-select the user's choice never reaches the ref and is reset on the next render; on aegov-checkbox and aegov-toggle the ref becomes the string "false" and the checked state is never bound; on aegov-radio it overwrites each radio's own value. Bind the value and listen for the component's event instead:
| Component | Bind | Listen for | New value |
|---|---|---|---|
aegov-select |
:value |
@aegovSelectChange |
$event.detail.value |
aegov-checkbox |
:is-checked |
@aegovCheckboxChange |
$event.detail.checked |
aegov-toggle |
:is-checked |
@aegovToggleChange |
$event.detail.checked |
aegov-radio in an aegov-radio-group |
:is-checked on each radio |
@aegovRadioGroupChange on the group |
$event.detail.value |
<template>
<aegov-select :value="district" @aegovSelectChange="district = $event.detail.value">
<aegov-select-option value="dubai">Dubai</aegov-select-option>
<aegov-select-option value="abu-dhabi">Abu Dhabi</aegov-select-option>
</aegov-select>
<aegov-checkbox
field-id="terms"
label="I accept the terms"
:is-checked="acceptsTerms"
@aegovCheckboxChange="acceptsTerms = $event.detail.checked"
/>
<aegov-toggle
field-id="alerts"
label="Email me updates"
:is-checked="wantsAlerts"
@aegovToggleChange="wantsAlerts = $event.detail.checked"
/>
<aegov-radio-group
name="delivery"
label="Delivery"
@aegovRadioGroupChange="delivery = $event.detail.value"
>
<aegov-radio field-id="delivery-standard" value="standard" label="Standard delivery" :is-checked="delivery === 'standard'" />
<aegov-radio field-id="delivery-express" value="express" label="Express delivery" :is-checked="delivery === 'express'" />
</aegov-radio-group>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const district = ref('');
const acceptsTerms = ref(false);
const wantsAlerts = ref(false);
const delivery = ref('standard');
</script>
If you want v-model on one of those, use its typed component (above), or wrap the tag once in your own app:
<!-- AeSelect.vue -->
<template>
<aegov-select :value="modelValue" @aegovSelectChange="emit('update:modelValue', $event.detail.value)">
<slot />
</aegov-select>
</template>
<script setup lang="ts">
defineProps<{ modelValue: string }>();
const emit = defineEmits<{ 'update:modelValue': [string] }>();
</script>
Template refs and imperative methods
On a tag, the ref gives you the underlying custom element. On a typed component, the ref is the Vue component and the element is its $el. Component methods are async.
<template>
<aegov-button @aegovButtonClick="modal?.show()">Review submission</aegov-button>
<aegov-modal ref="modal" label="Confirm submission">
<p>Submit your application for review?</p>
<aegov-button variant="primary" @aegovButtonClick="modal?.close()">Confirm</aegov-button>
</aegov-modal>
</template>
<script setup lang="ts">
import { useTemplateRef } from 'vue';
const modal = useTemplateRef<HTMLAegovModalElement>('modal');
</script>
For form components, validate() and setCustomValidity() are the ones you will use most:
<template>
<aegov-input ref="emiratesId" name="emiratesId" is-required />
<aegov-button @aegovButtonClick="check">Check</aegov-button>
</template>
<script setup lang="ts">
import { useTemplateRef } from 'vue';
const emiratesId = useTemplateRef<HTMLAegovInputElement>('emiratesId');
async function check() {
const result = await emiratesId.value?.validate('manual');
if (!result?.valid) emiratesId.value?.focus();
}
</script>
Tabs and other required identifiers
aegov-tab and aegov-tab-panel pair up by tab-id:
<template>
<aegov-tabs default-open="overview">
<aegov-tab slot="tabs" tab-id="overview">Overview</aegov-tab>
<aegov-tab slot="tabs" tab-id="documents">Documents</aegov-tab>
<aegov-tab-panel tab-id="overview">Application overview</aegov-tab-panel>
<aegov-tab-panel tab-id="documents">Uploaded documents</aegov-tab-panel>
</aegov-tabs>
</template>
Note the slot="tabs" attribute — it assigns the triggers to the tab strip. Slot assignment on custom elements uses the plain slot attribute, not Vue's <template #name> syntax, because these are native slots rather than Vue slots.
TypeScript
Token and payload types come from the core package:
import type {
ButtonVariant,
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);
}
RTL support
Set dir on the document or on a subtree and everything flips, including the body and heading font stacks.
<template>
<div :dir="locale === 'ar' ? 'rtl' : 'ltr'" :lang="locale">
<aegov-button variant="primary">
{{ locale === 'ar' ? 'إرسال الطلب' : 'Submit application' }}
</aegov-button>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const locale = ref('ar');
</script>
If locale is switchable at runtime, set it on the document element rather than only on a wrapper — portal-based components (toast, dropdown, popover, datepicker, modal and drawer) render into document.body, outside your Vue tree.
Server-side rendering and Nuxt
Custom elements are browser-only, so under Nuxt the components register on the client. Install the packages and Tailwind:
npm install @aegov/designsystem @aegov/designsystem-vue
npm install -D tailwindcss @tailwindcss/vite
Register the plugin on the client only, after Nuxt has hydrated the page. In Nuxt 4 the file goes in app/plugins/; in Nuxt 3 it goes in plugins/ at the project root. A plugin in the wrong folder is silently ignored and nothing renders.
// app/plugins/aegov.client.ts ← the .client suffix keeps it out of the server bundle
export default defineNuxtPlugin((nuxtApp) => {
// Register the components only after Vue has hydrated the server-rendered HTML.
nuxtApp.hooks.hookOnce('app:suspense:resolve', async () => {
const { ComponentLibrary } = await import('@aegov/designsystem-vue');
nuxtApp.vueApp.use(ComponentLibrary);
});
});
Wait for hydration as shown, and import the package inside the hook, not at the top of the file: in development, importing @aegov/designsystem-vue registers its elements as soon as the module loads, which would be during hydration. Several components (form field, tabs, accordion, navbar, breadcrumbs, timeline and others) arrange their own children as soon as they register. If they register during hydration, Vue reports Hydration completed but contains mismatches and "repairs" the DOM, and much of their content disappears. For the same reason, don't wait for defineDesignSystem() in a Nuxt plugin, and use the custom element tags rather than the typed components, which register their elements during hydration.
Create the stylesheet with the same three lines as Step 2 (in Nuxt 3, use assets/css/main.css):
/* app/assets/css/main.css */
@import "tailwindcss";
@import "@aegov/designsystem/base";
@import "@aegov/designsystem/theme";
Then add these keys to your existing nuxt.config.ts (alongside the scaffold's compatibilityDate and devtools) to load the stylesheet, add the Tailwind plugin and set isCustomElement, so the server-side compiler agrees with the client:
// nuxt.config.ts
import tailwindcss from '@tailwindcss/vite';
export default defineNuxtConfig({
css: ['~/assets/css/main.css'],
vite: {
plugins: [tailwindcss()],
// Pre-bundle the package the plugin imports, so the dev server doesn't reload the page the first time.
optimizeDeps: { include: ['@aegov/designsystem-vue'] },
},
vue: {
compilerOptions: {
isCustomElement: (tag) => tag.startsWith('aegov-'),
},
},
});
Don't use v-model on aegov-* tags in Nuxt — the server build rejects it; use :value with @aegovInputValue as shown in the v-model section above.
Validation
Form components ship the validation surface: is-invalid, error-message and hint props, error and hint slots, the aegovValidate event, and validate() / setCustomValidity() methods.
<template>
<aegov-input
name="email"
type="email"
:is-invalid="!!error"
:error-message="error"
@aegovValidate="onValidate"
/>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import type { AegovValidationDetail } from '@aegov/designsystem';
const error = ref('');
function onValidate(e: CustomEvent<AegovValidationDetail<string>>) {
if (e.detail.trigger !== 'blur') return;
const ok = /\S+@\S+\.\S+/.test(String(e.detail.value));
error.value = ok ? '' : 'Enter a valid email address';
}
</script>
Common gotchas
v-model works on aegov-input and aegov-textarea only, and not at all with server-side rendering. On a select the user's choice never reaches the ref and is reset on the next render; on a checkbox or toggle the ref becomes the string "false" and the checked state is never bound; on radios it overwrites each radio's own value. Bind :value or :is-checked and listen for the change event, use the typed component, or write a thin wrapper component.
isCustomElement compiler option is missing (in development the console shows Failed to resolve component: aegov-button). Without it, every @aegov… listener silently stops firing and v-model does nothing. Add it as shown in Step 2.
@aegov-button-click silently does nothing — no error, no warning. Listen with the camelCase event name instead: @aegovButtonClick.
defineDesignSystem(), the components aren't registered on the first render, so Vue sets tabId="one" as an attribute, the browser lowercases it to tabid, and the component never receives it. Tags rendered later happen to work, and the development server registers every element up front, so the problem looks intermittent or shows only in production. Wait for defineDesignSystem() before mount(), as shown in the Introduction, and write attributes in kebab-case — tab-id="one", :tab-id="id" — which always work.
<aegov-tab slot="tabs">, not <template #tabs>. These are shadow/scoped DOM slots on a custom element, not Vue slots.
document.body. Template refs to the host still work; queries scoped to your component's root will not find the portalled content.