Accordion
<cui-accordion>
Live Example
123 Main St, Anytown, USA
Cras iaculis interdum tempor. Nunc non vulputate justo. Nam pellentesque lacus egestas diam porta, ac dignissim ante dictum. Ut viverra dui est, vitae eleifend diam cursus vel
Visa ending in 4242
Integer rhoncus feugiat tincidunt. Sed ac orci ullamcorper, mollis ligula ut, pretium ex. Donec ultricies facilisis aliquam. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aliquam vehicula lorem metus, nec posuere enim facilisis consequat. Duis vulputate erat dignissim enim condimentum ultricies. Nam vel consectetur turpis, eget sodales nunc. Ut vulputate eu odio eget cursus. Etiam vitae vehicula nunc.
{{ item }} (index {{ index }}, expanded: {{ expanded }})
Pellentesque interdum semper ipsum, ac auctor ante pretium at. In risus magna, dictum eget faucibus in, consectetur viverra urna. Vivamus sed arcu ligula. Sed rutrum, lacus sed dictum iaculis, velit massa maximus sem, sed elementum elit justo nec elit
Expanded item: {{ expandedItem ?? '(none)' }}
Documentation
An accessible accordion component for Vue.js, following the W3C ARIA Authoring Practices Guide (APG) Accordion Pattern. Renders a list of headers/buttons paired with collapsible panels, using the listItems prop to define each accordion segment.
Usage
<cui-accordion
v-model="expandedItem"
:list-items="['Section One', 'Section Two', 'Section Three']">
<template #panel-section-one>
Content for section one.
</template>
<template #panel-section-two>
Content for section two.
</template>
<template #panel-section-three>
Content for section three.
</template>
</cui-accordion>
Usage with Objects
When valueField is set, v-model emits the matching property's value instead of the full item object:
<cui-accordion
v-model="expandedValue"
:list-items="[
{ text: 'Billing Info', value: 'billing' },
{ text: 'Shipping Info', value: 'shipping' },
]"
text-field="text"
value-field="value">
<template #panel-billing-info>
Billing form fields go here.
</template>
<template #panel-shipping-info>
Shipping form fields go here.
</template>
</cui-accordion>
Props
| Name | Type | Default | Description |
|---|---|---|---|
| listItems | Array | [] |
Array of strings or objects. Each entry defines one accordion header/panel pair. |
| textField | String | — | Property name on each item object used as its display text and to derive the panel slot name. If omitted (or items are plain strings), the item itself is used as the text. |
| valueField | String | — | Property name on each item object used as its v-model value (see v-model Value Semantics below). |
| headingTag | String | 'h3' |
The HTML tag (or component) used to render each accordion header's wrapping element (e.g. 'h2', 'h4', 'div'). Should typically match the appropriate heading level for the surrounding page content. |
| expanderPosition | String | 'left' |
The side of the header the expand/collapse indicator is displayed on. Accepts 'left' or 'right'. |
| modelValue | Any / Array | — | The expanded panel's value (v-model) — see v-model Value Semantics below. When multiExpand is true, this is an array of expanded values. |
| multiExpand | Boolean | false |
When true, multiple panels can be expanded at the same time. When false, expanding a panel collapses any other expanded panel. |
| disabled | Boolean | false |
Disables all accordion headers. |
| readonly | Boolean | false |
Prevents toggling panels, but does not visually disable the headers. |
| noItemsMsg | String | 'No items available' |
Message displayed when listItems is empty. |
| id | String | auto | Base id used to generate unique header/panel element ids. |
v-model Value Semantics
cui-accordion's v-model does not track panel index — it tracks the value of the expanded item(s):
- If
valueFieldis not set,v-modelemits the entire list item (the string or object) for the expanded panel(s). - If
valueFieldis set and an expanded item is an object with a property matchingvalueField,v-modelemits that property's value. - If
valueFieldis set but the expanded item is not an object, or is an object without that property,v-modelfalls back to emitting the entire item (same as ifvalueFieldwere not set).
When multiExpand is true, v-model is an array of these values (one per expanded panel) instead of a single value.
Events
| Event Name | Payload | Description |
|---|---|---|
| update:model-value | Any / Array / null |
Emitted when the expanded panel(s) change. |
| change | Any / Array / null |
Emitted alongside update:model-value. |
Slots
Each item in listItems produces one named panel slot. The slot name is derived from the item's display text (the textField property value for objects, or the string itself for plain strings), sanitized by replacing any run of whitespace or non-alphanumeric characters with a single hyphen, lowercased, then prefixed with panel-.
For example:
"Section One"→#panel-section-one"Billing & Shipping"→#panel-billing-shipping
Note: Slot names are always lowercased because HTML attribute/element names (including
<template #slot-name>shorthand) are case-insensitive when parsed from in-DOM templates (e.g. markup written directly in a.cshtml/.htmlpage rather than a compiled.vueSingle File Component). Using lowercase, hyphenated slot names avoids any mismatch between the generated slot name and how the browser parses your template.
Each panel slot receives the following scoped props:
| Prop | Type | Description |
|---|---|---|
| item | Any | The original list item (string or object). |
| index | Number | The zero-based index of the item. |
| expanded | Boolean | Whether the panel is currently expanded. |
If a slot is not provided for an item, the panel falls back to rendering the item's display text.
Accessibility
Follows the W3C APG Accordion Pattern:
- Each header is rendered using the tag specified by
headingTag(defaulth3) wrapping a<button>(accordion-trigger), witharia-expandedreflecting the panel's expanded state andaria-controlspointing at the associated panel's id. - Each panel has
role="region"andaria-labelledbypointing back at its header button's id, and is hidden (v-show) when collapsed. - Keyboard support on the header buttons:
ArrowDown/ArrowUpmoves focus to the next/previous header button, wrapping around at the ends.Home/Endmoves focus to the first/last header button.Enter/Space(native<button>behavior) toggles the focused panel.
- When
disabled, header buttons are markeddisabledand removed from the tab order.
Animation
Panels expand and collapse with a smooth height transition, implemented via Vue's <Transition> component with JavaScript hooks (since CSS cannot transition to/from an auto height). The transition is automatically disabled for users who have prefers-reduced-motion: reduce set.
Related Components
- cui-Panel - A resizable panel component, useful for other layout needs.