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 Dropdowns
Address Contact number Currency symbol Date Emirates ID Name
Close
Home Documentation Components Accordion

Accordion

An Accordion helps effectively manage and organize content in an interactive, user-friendly manner. It enables content to be collapsed into separate sections that can be expanded upon user interaction — especially useful in environments with limited screen space.

Content Interactive
Status
Active
Introduced
4.0.x
View source code

Anatomy

The aegov-accordion component composes a wrapper with one or more aegov-accordion-item children. The parent owns shared configuration — icon style, heading size, single-open vs. multi-open behaviour, and first/last positioning — and propagates it to each item automatically.

Image showing anatomy of an accordion

Item Name Description
1 Trigger A real <button> wrapped in a heading element; toggles the item open or closed
2 Heading label The slotted or heading-property text announced by the trigger
3 Toggle icon Chevron or plus/cross indicator that reflects open state
4 Content panel The collapsible region shown when the item is open

Options

The accordion has options for different use cases. These are considered the basic properties applicable to an accordion.

Single (default)

Only one item stays open at a time. Opening this closes item one.

Multiple

Any number of items can be open together. Opening this does not close item one.

Single vs. multiple open

By default the accordion behaves like a radio group — opening one item collapses the rest. Set is-multiple="true" to allow any number of items to be expanded at once.

Chevron (default)

We collect only the data necessary to provide the service.

Plus / cross

We collect only the data necessary to provide the service.

Toggle icon

The icon property selects the visual indicator next to each heading. chevron (default) rotates 180° as the item expands. plus rotates 45° to form a cross (×) when open.

Default

First item content. Second item content.

is-bordered="true"

First item content. Second item content.

Bordered container

Set is-bordered="true" to wrap the entire accordion in a rounded outline. Use this when the accordion sits on a page background that needs a visible boundary; omit it when the surrounding card already provides one.

Default open item

Use default-open with a zero-based index to expand a specific item on initial render. This is useful for highlighting the most important question in an FAQ.

First section content. Second section content — open on initial render. Third section content.
<aegov-accordion default-open="1">
  <aegov-accordion-item heading="Section A">First section content.</aegov-accordion-item>
  <aegov-accordion-item heading="Section B (open by default)">Second section content — open on initial render.</aegov-accordion-item>
  <aegov-accordion-item heading="Section C">Third section content.</aegov-accordion-item>
</aegov-accordion>

Size

The size property sets the heading typography. Three tokens are available: sm, base (default), and lg. The body content keeps its inherited size, and the trigger's heading text and toggle icon scale together: 20px icon at sm, 24px (default) at base, 26px at lg.

Token Heading size
sm 14px
base 16px (default)
lg 18px

Size is a responsive property and can accept a token per breakpoint.

Compact size suits dense administrative interfaces. The default size, suitable for most page contexts. Large size works well as a primary FAQ on a landing page.
<aegov-accordion size="sm">
  <aegov-accordion-item heading="Small heading">Compact size suits dense administrative interfaces.</aegov-accordion-item>
</aegov-accordion>
<aegov-accordion size="base">
  <aegov-accordion-item heading="Base heading">The default size, suitable for most page contexts.</aegov-accordion-item>
</aegov-accordion>
<aegov-accordion size="lg">
  <aegov-accordion-item heading="Large heading">Large size works well as a primary FAQ on a landing page.</aegov-accordion-item>
</aegov-accordion>

Responsive size

size can also be set per breakpoint using a responsive string. Only the three tokens above — sm, base, lg — are valid values at any breakpoint. Pick a value to preview what it resolves to.

Resize your browser to see the heading scale.
<aegov-accordion size="sm md:base xl:lg">
  <aegov-accordion-item heading="Resizes with the viewport">
    Resize your browser to see the heading scale across the sm, md, and xl breakpoints.
  </aegov-accordion-item>
</aegov-accordion>

Heading level

The heading-level property controls which HTML heading element (h1–h6) wraps each trigger button. Setting the correct level keeps the page outline meaningful for screen readers. The default is 3; use a lower number when the accordion is the primary content structure on a page, or a higher number when it sits inside an existing heading hierarchy.

heading-level="2"

Submit your application through the business licensing portal.

heading-level="3" (default)

Reach us on 800-UAE-GOV or visit any service centre.
<!-- Triggers render inside <h2> elements -->
<aegov-accordion heading-level="2">
  <aegov-accordion-item heading="Trade licence application">
    Submit your application through the business licensing portal.
  </aegov-accordion-item>
</aegov-accordion>

Custom heading slot

When the trigger needs richer markup — formatting, an inline icon, a status badge — use the accordion-item-heading slot instead of the heading property. The slot replaces the plain text heading entirely.

Step 1. Verify your identity Required Use your Emirates ID to confirm your identity before proceeding. Step 2. Submit your documents Upload the supporting documents listed in the application form.
<aegov-accordion>
  <aegov-accordion-item>
    <span slot="accordion-item-heading">
      <strong>Step 1.</strong> Verify your identity
      <aegov-badge variant="aegreen" size="sm">Required</aegov-badge>
    </span>
    Use your Emirates ID to confirm your identity before proceeding.
  </aegov-accordion-item>
  <aegov-accordion-item>
    <span slot="accordion-item-heading">
      <strong>Step 2.</strong> Submit your documents
    </span>
    Upload the supporting documents listed in the application form.
  </aegov-accordion-item>
</aegov-accordion>

Disabled items

Set is-disabled="true" on an individual item to prevent it from being opened. The trigger renders as visually muted and remains focusable, but is marked with aria-disabled="true" to communicate its disabled state to assistive technology.

This service is currently accepting applications. This section is not yet available. This service is currently accepting applications.
<aegov-accordion>
  <aegov-accordion-item heading="Active service">This service is currently accepting applications.</aegov-accordion-item>
  <aegov-accordion-item heading="Coming soon" is-disabled="true">This section is not yet available.</aegov-accordion-item>
  <aegov-accordion-item heading="Active service">This service is currently accepting applications.</aegov-accordion-item>
</aegov-accordion>

Rich text content

The default slot of aegov-accordion-item accepts any HTML — lists, paragraphs, tables, or nested components. The content panel expands to fit whatever is placed inside it.

Submit the following when applying for a trade licence:

  • Completed application form
  • Emirates ID (both sides)
  • Passport copy
  • Proof of business address

Nested accordion

A nested accordion places a single aegov-accordion element inside the item of a parent accordion. heading-level auto-increments by one for the nested accordion unless it is set explicitly, keeping the document outline correct without extra configuration.

To receive a passport, you must follow the steps mentioned here

We collect only the data necessary to provide the service. By using this service you agree to the terms set out in the official agreement.
Second item content. Third item content.
<aegov-accordion is-bordered="true">
  <aegov-accordion-item heading="How can I get a passport">
    <p>To receive a passport, you must follow the steps mentioned here</p>
    <aegov-accordion icon="plus">
      <aegov-accordion-item heading="Privacy policy">We collect only the data necessary to provide the service.</aegov-accordion-item>
      <aegov-accordion-item heading="Terms of service">By using this service you agree to the terms set out in the official agreement.</aegov-accordion-item>
    </aegov-accordion>
  </aegov-accordion-item>
  <aegov-accordion-item heading="Documents required">Second item content.</aegov-accordion-item>
  <aegov-accordion-item heading="Appointment booking">Third item content.</aegov-accordion-item>
</aegov-accordion>

RTL support

The accordion is direction-agnostic. When the document or any ancestor has dir="rtl", the trigger's flex-row layout reverses automatically — placing the toggle icon on the visual left — and a dedicated [dir="rtl"] rule right-aligns the heading text. No additional configuration is required.

مكتبة مشتركة من مكوّنات واجهة المستخدم مبنية وفق معيار بصري وإمكانية وصول موحّدة. افتح طلب دعم على مستودع المشروع، أو تواصل مع فريق نظام التصميم.
<div dir="rtl">
  <aegov-accordion is-bordered="true" default-open="0">
    <aegov-accordion-item heading="ما هو نظام التصميم الإماراتي؟">
      مكتبة مشتركة من مكوّنات واجهة المستخدم مبنية وفق معيار بصري وإمكانية وصول موحّدة.
    </aegov-accordion-item>
    <aegov-accordion-item heading="كيف يمكنني الإبلاغ عن خطأ؟">
      افتح طلب دعم على مستودع المشروع، أو تواصل مع فريق نظام التصميم.
    </aegov-accordion-item>
  </aegov-accordion>
</div>

Usage

Here is the recommended usage of an accordion on any website or application. These are recommended usage guides, however the developer must use the best practices of web and application development to accurately use this component.

Use for optional or secondary content

Reach for an accordion when content is helpful but not essential to every visitor — FAQs, supporting details, optional settings. If most users need to read it, show it directly instead of hiding it behind a click.

Write a heading that stands alone

A trigger heading should make sense out of context — "Processing times", not "More info". Screen reader users often scan headings alone before deciding what to expand.

Default-open the most relevant item, sparingly

Use default-open to surface the single most important item — the top FAQ, an active step — not to open several items at once by default, which just recreates a long unstructured page.

Do not use an accordion for primary navigation

An accordion hides content behind an interaction. Primary navigation and steps a user must always see belong in a visible menu, tabs, or a stepper — not collapsed by default.

Do not bury required or safety-critical information

Fees, deadlines, eligibility requirements, or anything a user must see to complete a task should not be hidden inside a collapsed item they might never open.

Do not nest accordions more than one level deep

A single level of nesting (an accordion inside one item) is supported and has correct heading-level cascading. Nesting further nearly always signals the content should be restructured instead — deep nesting is hard to scan and hard to navigate with a keyboard.

Do not use an accordion in place of a short list

If every item's content is one short sentence, showing it directly is faster to scan than clicking through each trigger. Collapsing only earns its keep when the content is substantial enough to need hiding.

API reference

The following are the properties and references of an accordion

aegov-accordion default properties

AttributeDescriptionTypeDefault

field-id

DOM id for the accordion wrapper element. Auto-generated if omitted.

string

auto-generated

is-multiple

When true, multiple items can be open at the same time. Default behaves like a radio group — opening one item closes the rest.

boolean

false

default-open

Zero-based index of the item to open on initial render.

number

undefined

icon

Toggle indicator style. chevron rotates 180°; plus rotates 45° to form a cross (×) when open.

chevron | plus

chevron

is-bordered

Adds an outer border and rounded corners around the entire accordion.

boolean

false

size

Heading typography size. Accepts a single token or a Tailwind-style responsive string.

sm | base | lg

base

heading-level

HTML heading element (1–6) wrapping each trigger button. Cascaded to all child items; auto-incremented by 1 for a nested accordion unless set explicitly.

number

3

aegov-accordion-item default properties

AttributeDescriptionTypeDefault

heading

Trigger text. Ignored when the accordion-item-heading slot has content.

string

undefined

is-disabled

Disables the trigger so the item cannot be opened or closed. Sets aria-disabled="true" rather than the native disabled attribute, so the trigger remains focusable.

boolean

false

is-open, icon, size, heading-level

Set automatically by the parent aegov-accordion. Setting these directly on an item is overwritten the next time the parent syncs.

various

various

Slots

ComponentSlotDescription

aegov-accordion

(default)

Place one or more aegov-accordion-item children here.

aegov-accordion-item

accordion-item-heading

Custom heading content. Overrides the heading property when supplied.

aegov-accordion-item

(default)

Body content shown when the item is expanded.

Events

EventsDescriptionComponentDetail

aegovAccordionItemToggle

Fired when an item's trigger is activated, requesting open or close. The parent aegov-accordion intercepts this event and writes the resolved isOpen back onto the item — the event itself does not mean the item has already toggled. Although the event is dispatched with bubbles: true, the parent aegov-accordion calls stopPropagation() on its own internal listener, so it never reaches a bubble-phase listener on the accordion itself or any further ancestor. Listen on each aegov-accordion-item directly, or attach a capture-phase listener (third argument true) on an ancestor.

aegov-accordion-item

CustomEvent<{ open: boolean }>

<aegov-accordion id="faq">
  <aegov-accordion-item id="faq-a" heading="A">A</aegov-accordion-item>
  <aegov-accordion-item id="faq-b" heading="B">B</aegov-accordion-item>
</aegov-accordion>

<script>
  // aegov-accordion stops this event from bubbling past the item itself
  // (it intercepts it internally to sync isOpen), so listen on each item
  // directly rather than on the parent aegov-accordion.
  document.querySelectorAll('#faq aegov-accordion-item').forEach((item) => {
    item.addEventListener('aegovAccordionItemToggle', (e) => {
      console.log('Item toggle requested, open =', e.detail.open, 'target =', e.target.id);
    });
  });
</script>

Pass-through attributes

AttributeNotesForwards to

aria-*

Not automatically forwarded. Apply directly to <aegov-accordion> or <aegov-accordion-item>.

n/a

data-*

Not automatically forwarded. Apply directly to <aegov-accordion> or <aegov-accordion-item>.

n/a

Neither component forwards attributes to inner elements — aegov-accordion.tsx's render() passes no spread props to its wrapping <div> beyond a fixed class list, and aegov-accordion-item.tsx does the same for its trigger <button>. Set attributes directly on the host element where they are needed.

Notes

The following notes are applicable of this component.

Built-in accessibility

  • Each trigger renders as a real <button> with aria-expanded reflecting the open state and aria-controls linked to its panel.
  • Each panel uses role="region" and aria-labelledby pointing at its trigger, so screen readers announce the heading–content relationship.
  • Enter and Space toggle the focused item — free, native <button> behaviour, no custom key handling needed.
  • Arrow-key navigation (ArrowUp / ArrowDown / Home / End) moves focus between item triggers within the same accordion, matching the WAI-ARIA Accordion pattern. A nested accordion's own triggers are handled by its own keydown listener and does not interfere with the parent's.
  • Collapsed panels get the HTML inert attribute on their content wrapper. This removes every focusable descendant — buttons, links, inputs — from both the tab order and the accessibility tree in one step, so there is no focus leaking into hidden content.
  • Disabled items set aria-disabled="true" on the trigger (never the native disabled attribute) and do not emit a toggle event when activated, but the trigger stays focusable.

Developer responsibility

The following is required for a developer to add additionally or pay attention to regarding this component.

  • Provide a meaningful heading (or accordion-item-heading slot) on every item — without it the trigger announces to screen readers as just "button".
  • When using default-open, make sure the index actually points at a real child item.
  • aegov-accordion-item must always be used inside aegov-accordion. Using it standalone logs a console error and its toggle behaviour will not be wired up by any parent.

Additional notes

  • aegovAccordionItemToggle is dispatched with bubbles: true (verified against the compiled component — createEvent(this, "aegovAccordionItemToggle", 7), where flag 7 sets bubbles, composed, and cancelable all true) — but in practice it never reaches a bubble-phase listener on the parent aegov-accordion or beyond, because the parent's own internal listener (attached directly on each item to sync isOpen) calls stopPropagation(). Attach your listener to each aegov-accordion-item directly, or use a capture-phase listener on an ancestor if you need a single listener.
  • heading-level cascades from parent to children automatically, and auto-increments by 1 for an accordion nested inside another accordion's item — so a nested accordion's triggers render one heading level deeper by default, keeping the outline correct without extra configuration.
  • Focusable controls nested inside a collapsed panel are automatically excluded from the tab order via inert. You do not need to manually disable or hide them.

Keyboard support

Key Action
Enter, Space Toggle the focused accordion item.
ArrowDown Move focus to the next accordion trigger.
ArrowUp Move focus to the previous accordion trigger.
Home Move focus to the first accordion trigger.
End Move focus to the last accordion trigger.
Tab Move focus to the next focusable element on the page.
Shift + Tab Move focus to the previous focusable element on the page.