> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/expandable-section.md).

# 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.

```html
<!-- 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>
```

```js
// 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.

```html
<!-- 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.                        |

### 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 <support@avonni.app> for assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/lwc-components/core-components/expandable-section.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.