Expandable Section

avonni-expandable-section

A titled section that users can expand or collapse to show or hide its content.

Overview

Expandable Section is a Lightning Web Component that wraps content in a titled section that can be collapsed and expanded.

Use it in your own Lightning Web Components to organize long pages into scannable, collapsible regions. You set the title and variant, choose whether it's collapsible and initially open or closed, and place any markup inside its slots.

Use Cases

• Form grouping: Break a long form into collapsible sections.
• FAQ lists: Show questions that expand to reveal answers.
• Detail panels: Hide secondary record details until requested.
• Settings groups: Organize related settings under shaded headers.
• Custom headers: Use the title slot to add an icon or badge to the header.

---

Variant Guidelines

Variant	Use Case
base	Lightweight grouping within a card or panel.
shaded	Distinct, visually separated sections on a page.

---

Use Case Examples

Example 1: Collapsible shaded section

Scenario: Show shipping information in a shaded, collapsible section and react when the user toggles it.

<!-- shippingDetails.html -->
<template>
    <avonni-expandable-section
        title="Shipping information"
        variant="shaded"
        collapsible
        closed-icon-alternative-text="Show details"
        opened-icon-alternative-text="Hide details"
        ontoggle={handleToggle}
    >
        <p>Orders ship within 1-2 business days via standard carrier.</p>
    </avonni-expandable-section>
</template>

// shippingDetails.js
import { LightningElement } from 'lwc';

export default class ShippingDetails extends LightningElement {
    handleToggle(event) {
        const isClosed = event.detail.closed; // true when collapsed
    }
}

Result: A shaded section with shipping text that collapses and expands; toggling fires toggle with the new closed state.

Example 2: Section with a custom title slot

Scenario: Add an icon next to the header label using the title slot, and start the section collapsed.

<!-- faqSection.html -->
<template>
    <avonni-expandable-section variant="base" collapsible closed>
        <span slot="title" class="slds-grid slds-grid_vertical-align-center">
            <lightning-icon
                icon-name="utility:info"
                size="x-small"
                class="slds-m-right_x-small"
            ></lightning-icon>
            <span class="slds-text-title_bold">Frequently asked questions</span>
        </span>
        <ul class="slds-list_dotted">
            <li>How do I track my order?</li>
            <li>What is the return policy?</li>
        </ul>
    </avonni-expandable-section>
</template>

Result: A collapsed base section whose header shows an info icon beside bold title text; expanding it reveals the FAQ list.

---

Specifications

Attributes

Name	Description	Type	Default	Required
closed	If present, close the section.	Boolean	false
closed-icon-alternative-text	Alternative text for the closed icon.	String	—
collapsible	If present, the section is collapsible.	Boolean	false
opened-icon-alternative-text	Alternative text for the open icon.	String	—
title	The title can include text, and is displayed in the header.	String	—
variant	Variant of the section. Valid values include base and shaded.	String	"base"

Methods

Name	Description	Argument Name	Argument Type	Argument Description
focus	Set the focus on the collapse button.

Slots

Slot	Description
default	Placeholder for your content in the main section.
title	Placeholder for your content in the title.

Custom Events

toggle

The event fired when the expandable section is closed or opened.

The toggle event returns the following parameters.

Parameter	Type	Description
closed	boolean

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

toggle

The event fired when the expandable section is closed or opened.

The toggle event returns the following parameters.

Parameter	Type	Description
closed	boolean

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-expandable-section-base-header-color-background	color	transparent
--avonni-expandable-section-base-header-color-border	color	transparent
--avonni-expandable-section-base-header-color-border-active	color	—
--avonni-expandable-section-base-header-text-color	color	#080707
--avonni-expandable-section-base-header-text-color-focus	color	#080707
--avonni-expandable-section-base-header-text-color-hover	color	#080707
--avonni-expandable-section-base-header-text-decoration-focus	color	none
--avonni-expandable-section-base-header-font-size	font	1rem
--avonni-expandable-section-base-header-font-style	font	normal
--avonni-expandable-section-base-header-font-weight	font	400
--avonni-expandable-section-base-header-spacing-block-start	dimension	0rem
--avonni-expandable-section-base-header-spacing-block-end	dimension	0rem
--avonni-expandable-section-base-header-icon-color-foreground-default	color	—
--avonni-expandable-section-base-header-icon-color-foreground-default-hover	color	—
--avonni-expandable-section-base-header-icon-color-foreground-default-focus	color	—
--avonni-expandable-section-content-spacing-block-start	dimension	—
--avonni-expandable-section-content-spacing-block-end	dimension	—
--avonni-expandable-section-shaded-header-color-background	color	#f3f2f2
--avonni-expandable-section-shaded-header-color-border	color	transparent
--avonni-expandable-section-shaded-header-text-color	color	#080707
--avonni-expandable-section-shaded-header-text-color-focus	color	#080707
--avonni-expandable-section-shaded-header-text-color-hover	color	#080707
--avonni-expandable-section-shaded-header-text-decoration-focus	color	none
--avonni-expandable-section-shaded-header-font-size	font	1rem
--avonni-expandable-section-shaded-header-font-style	font	normal
--avonni-expandable-section-shaded-header-font-weight	font	400
--avonni-expandable-section-shaded-header-spacing-block-start	dimension	0.75rem
--avonni-expandable-section-shaded-header-spacing-block-end	dimension	0.75rem
--avonni-expandable-section-shaded-header-icon-color-foreground-default	color	—
--avonni-expandable-section-shaded-header-icon-color-foreground-default-hover	color	—
--avonni-expandable-section-shaded-header-icon-color-foreground-default-focus	color	—

Key Considerations

• Collapsible required for toggling: Without collapsible, the section stays open and the toggle control is hidden.
• Initial state: Use closed to start collapsed; omit it to start expanded.
• Slots: Use the title slot for rich headers and the default slot for any body markup.
• Accessibility: Provide both icon alternative-text attributes so the toggle state is announced.
• Variant: shaded adds a background to separate sections; base is lighter weight.
• Best Practice: Set closed-icon-alternative-text and opened-icon-alternative-text so screen readers announce the toggle state, and use shaded to visually separate sections on dense pages.

---

Troubleshooting Common Issues

• Section won't collapse: Confirm the collapsible attribute is present.
• Toggle event not firing: Verify ontoggle is wired and read event.detail.closed.
• Custom header not showing: Ensure the custom markup uses slot="title".
• If issues persist: Contact our support team at [email protected] for assistance.