The Quasar expansion item, q-expansion-item, is a list item that opens to show more content. On its own it's a collapsible panel. Give several of them the same group and you get an accordion where only one stays open, the classic FAQ list. Nest them in a drawer and you have a navigation menu with sections. This post covers all three with working code for Quasar 2.35.2, plus the details that trip people up: groups that leak across the page, headers that lose their accessible name, and links that won't toggle.
QExpansionItem renders a QItem as its header, so it belongs inside a q-list:
<template>
<q-list bordered separator class="rounded-borders">
<q-expansion-item
icon="local_shipping"
label="Shipping"
caption="Delivery times and costs"
default-opened
>
<q-card>
<q-card-section>Orders ship within two working days.</q-card-section>
</q-card>
</q-expansion-item>
<q-expansion-item v-model="returnsOpen" icon="undo" label="Returns">
<q-card>
<q-card-section>Return any item within 30 days.</q-card-section>
</q-card>
</q-expansion-item>
</q-list>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const returnsOpen = ref(false)
</script>The props you'll use most:
| Prop | Does |
|---|---|
label, caption | Header text and a smaller second line |
icon | An icon on the left of the header |
default-opened | Starts open; v-model overrides it |
v-model | A boolean for the open state, to read or set it from code |
expand-separator | Separator lines above and below an open item |
dense, dense-toggle | Tighter header, smaller arrow |
switch-toggle-side | Puts the arrow on the left |
duration | Animation length in ms (default 300) |
The item also has show(), hide() and toggle() methods, and emits show, hide, after-show and after-hide. after-show fires when the opening animation ends, which is the moment to scroll the item into view.
One detail worth knowing: the content is always rendered. A closed item hides it with display: none, so the content is in the server-rendered HTML and its components keep their state while closed. If the body is expensive, such as a chart, put a v-if on it yourself, bound to v-model.
Give every item the same group name and opening one closes the one that was open:
<q-list bordered class="rounded-borders">
<q-expansion-item group="pricing-faq" label="Can I change plans later?">
<div class="q-px-md q-pb-md">Yes. Upgrades apply at once.</div>
</q-expansion-item>
<q-expansion-item group="pricing-faq" label="Do you offer refunds?">
<div class="q-px-md q-pb-md">Within 14 days of purchase.</div>
</q-expansion-item>
</q-list>How group works matters more than it looks. Quasar keeps one registry of open items per group name for the whole app, not per list. Two accordions that share a name, say two group="faq" blocks on the same page or a page and a dialog, close each other's items. Use a name that is unique to each list (pricing-faq, shipping-faq), or build it from an id when the component is reused.
Two more consequences:
default-opened on a single item, usually the first.group only closes the previous item. It doesn't stop the user from closing the open one, so an accordion can end up with everything closed. That's usually fine for an FAQ.A real FAQ list comes from data and usually wants its own header styling. The header slot replaces the header content and receives expanded, toggle, show, hide and detailsId:
<template>
<section aria-labelledby="faq-title" class="q-mx-auto" style="max-width: 720px">
<h2 id="faq-title" class="text-h5">Frequently asked questions</h2>
<q-list bordered class="rounded-borders">
<q-expansion-item
v-for="faq in faqs"
:key="faq.question"
group="pricing-faq"
:label="faq.question"
expand-icon="add"
expanded-icon="remove"
expand-separator
>
<template #header="{ expanded }">
<q-item-section>
<span class="text-subtitle1" :class="{ 'text-weight-medium': expanded }">
{{ faq.question }}
</span>
</q-item-section>
</template>
<div class="q-px-md q-pb-md text-grey-8">{{ faq.answer }}</div>
</q-expansion-item>
</q-list>
</section>
</template>
<script setup lang="ts">
const faqs = [
{ question: 'Can I change plans later?', answer: 'Yes. Upgrades apply at once; downgrades apply at the next billing date.' },
{ question: 'Do you offer refunds?', answer: 'Within 14 days of purchase, no questions asked.' },
{ question: 'Is there a free trial?', answer: 'Every plan has a 14-day trial, no card needed.' },
]
</script>What each piece does:
expand-icon and expanded-icon swap the arrow for a plus that becomes a minus. Setting expanded-icon also turns off the arrow's rotation, which would otherwise spin the minus sign.:label next to the header slot. The slot hides the label visually, but Quasar still uses it to build the toggle's accessible name (Expand "Can I change plans later?"). Without a label, a screen reader hears only "Expand". If you don't want the label, set toggle-aria-label instead.expanded in the slot lets the open question turn bold. The arrow stays, because the slot replaces only the header's content, not the toggle.section with a heading gives the list a landmark and a title, so the questions aren't a loose stack of buttons.The header already has role="button", aria-expanded and aria-controls pointing at the content, and it responds to Enter and Space. You get a correct disclosure pattern without extra work.
popup draws each item as a bordered card. Closed cards are inset from the sides; the open one widens to full width with space above and below, so it stands apart from its neighbours. It's a common look for FAQ pages. It works with the same group, header slot and icons as above.
In a navigation drawer, expansion items group links under section headers. content-inset-level indents the children so they line up under the parent's label, and default-opened can read the route so the current section starts open:
<template>
<q-list padding>
<q-item clickable v-ripple to="/dashboard">
<q-item-section avatar><q-icon name="dashboard" /></q-item-section>
<q-item-section>Dashboard</q-item-section>
</q-item>
<q-expansion-item
icon="receipt_long"
label="Billing"
group="nav"
:content-inset-level="1"
:default-opened="route.path.startsWith('/billing')"
>
<q-item clickable v-ripple to="/billing/invoices">
<q-item-section>Invoices</q-item-section>
</q-item>
<q-item clickable v-ripple to="/billing/plans">
<q-item-section>Plans</q-item-section>
</q-item>
</q-expansion-item>
<q-expansion-item icon="settings" label="Settings" group="nav" to="/settings" :content-inset-level="1">
<q-item clickable v-ripple to="/settings/team">
<q-item-section>Team</q-item-section>
</q-item>
</q-expansion-item>
</q-list>
</template>
<script setup lang="ts">
import { useRoute } from 'vue-router'
const route = useRoute()
</script>Look at the Settings item: it has a to. When an expansion item is a link, clicking the header navigates and only the arrow toggles it. The arrow becomes its own focusable button for keyboard users. If you want the arrow-only behavior without a link, for example when the header holds a checkbox, use expand-icon-toggle.
header-inset-level does the same as content-inset-level for the header, which is how you align a parent that has no icon with siblings that do.
How do I keep only one Quasar expansion item open? Give all of them the same group value, unique to that list.
How do I open an item from code? Bind v-model to a boolean, or call show() through a template ref.
Why does opening an FAQ item close one in another section? Both lists use the same group name. Group names are shared across the app.
Can I put a Quasar expansion item outside a q-list? It renders, but the header is a QItem and is styled to sit in a list. Keep it in q-list for the right padding and separators.
The FAQs Block has 5 FAQ section Components. Two are Free: a two-column list of questions and answers, and a centered accordion of q-expansion-items in popup mode with plus and minus icons and a header slot, the same pattern as above. They don't set group, so add one if you want only one answer open at a time.