npm package: @m3e/expansion-panel
Description: Expansion Panel for M3E
Author: matraic
Latest version: 1.3.1
Deprecated: Deprecated — use @m3e/web instead.

# @m3e/expansion-panel

The `@m3e/expansion-panel` package provides expressive, accessible components for organizing content in collapsible sections and coordinated groups. It includes:

- **`m3e-expansion-panel`** — An accessible, animated details-summary view for organizing content in collapsible sections. Supports custom header, content, actions, and toggle icon slots, configurable toggle position and direction, open/close states, lifecycle events, and rich theming via CSS custom properties for elevation, shape, spacing, and color.

- **`m3e-accordion`** — Organizes multiple expansion panels into a coordinated, accessible group. Supports single or multiple open panels via the `multi` attribute, expressive theming and shape control for grouped layouts, and manages open/close state across child panels for interactive disclosure patterns.

> **This package is part of [M3E](https://github.com/matraic/m3e) monorepo**, a unified suite of Material 3 web components. [Explore the docs](https://matraic.github.io/m3e) to see them in action.

## 📦 Installation

```bash
npm install @m3e/expansion-panel
```

## 💻 Editor Integration

This package includes a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) to support enhanced editor tooling and developer experience.

### Visual Studio Code

To enable autocomplete and hover documentation for `@m3e/expansion-panel`, install the [Custom Elements Manifest Language Server](https://marketplace.visualstudio.com/items?itemName=pwrs.cem-language-server-vscode) extension. It will automatically detect the manifest bundled with this package and surface tag names, attributes, slots, and events in supported files.

Alternately, you can explicitly reference the `html-custom-data.json` and `css-custom-data.json` in your workspace settings:

```json
{
  "html.customData": ["./node_modules/@m3e/expansion-panel/dist/html-custom-data.json"],
  "css.customData": ["./node_modules/@m3e/expansion-panel/dist/css-custom-data.json"]
}
```

## 🚀 Native Module Support

This package uses [JavaScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#module_specifiers). To use it directly in a browser without a bundler, use a module script similar to the following.

```html
<script type="module" src="/node_modules/@m3e/expansion-panel/dist/index.js"></script>
```

In addition, you must use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) to include dependencies.

```html
<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js",
      "@m3e/core/bidi": "/node_modules/@m3e/core/dist/bidi.js"
    }
  }
</script>
```

> For production, use index.min.js and bidi.min.js for faster load times.

## 🗂️ Elements

- `m3e-expansion-panel` — An expandable details-summary view.
- `m3e-accordion` — Combines multiple expansion panels in to an accordion.

## 🧪 Examples

The following example illustrates the basic use of the `m3e-accordion` and `m3e-expansion-panel` components.

```html
<m3e-accordion>
  <m3e-expansion-panel>
    <span slot="header">Panel 1</span>
    I am content for the first expansion panel
  </m3e-expansion-panel>
  <m3e-expansion-panel>
    <span slot="header">Panel 2</span>
    I am content for the second expansion panel
  </m3e-expansion-panel>
</m3e-accordion>
```

## 📖 API Reference

### 🗂️ Accordion

This section details the attributes, slots and CSS custom properties available for the `m3e-accordion` component.

#### ⚙️ Attributes

| Attribute | Type      | Default | Description                                                     |
| --------- | --------- | ------- | --------------------------------------------------------------- |
| `multi`   | `boolean` | `false` | Whether multiple expansion panels can be open at the same time. |

#### 🧩 Slots

| Slot        | Description                          |
| ----------- | ------------------------------------ |
| _(default)_ | Renders the panels of the accordion. |

#### 🎛️ CSS Custom Properties (applies to slotted panels)

| Property                                | Description                          |
| --------------------------------------- | ------------------------------------ |
| `--m3e-expansion-panel-container-color` | Background color for grouped panels. |
| `--m3e-expansion-panel-elevation`       | Elevation for grouped panels.        |
| `--m3e-expansion-panel-open-shape`      | Shape for open grouped panels.       |
| `--m3e-expansion-panel-shape`           | Shape for closed grouped panels.     |

---

### 🗂️ Expansion Panel

This section details the attributes, events, slots and CSS custom properties available for the `m3e-expansion-panel` component.

#### 🏷️ Attributes

| Attribute          | Type               | Default | Description                            |
| ------------------ | ------------------ | ------- | -------------------------------------- |
| `disabled`         | `boolean`          | `false` | Whether the element is disabled.       |
| `hide-toggle`      | `boolean`          | `false` | Whether to hide the expansion toggle.  |
| `open`             | `boolean`          | `false` | Whether the panel is expanded.         |
| `toggle-direction` | `"start" \| "end"` | `"end"` | The direction of the expansion toggle. |
| `toggle-position`  | `"start" \| "end"` | `"end"` | The position of the expansion toggle.  |

#### 🔔 Events

| Event Name | Description                                       |
| ---------- | ------------------------------------------------- |
| `opening`  | Emitted when the expansion panel begins to open.  |
| `opened`   | Emitted when the expansion panel has opened.      |
| `closing`  | Emitted when the expansion panel begins to close. |
| `closed`   | Emitted when the expansion panel has closed.      |

#### 🧩 Slots

| Slot          | Description                           |
| ------------- | ------------------------------------- |
| _(default)_   | Renders the detail of the panel.      |
| `header`      | Renders the header content.           |
| `actions`     | Renders the actions bar of the panel. |
| `toggle-icon` | Renders the expansion toggle icon.    |

#### 🎛️ CSS Custom Properties

| Property                                          | Description                                         |
| ------------------------------------------------- | --------------------------------------------------- |
| `--m3e-expansion-header-collapsed-height`         | Height of the header when collapsed.                |
| `--m3e-expansion-header-expanded-height`          | Height of the header when expanded.                 |
| `--m3e-expansion-header-padding-left`             | Left padding inside the header.                     |
| `--m3e-expansion-header-padding-right`            | Right padding inside the header.                    |
| `--m3e-expansion-header-spacing`                  | Spacing between header elements.                    |
| `--m3e-expansion-header-toggle-icon-size`         | Size of the toggle icon.                            |
| `--m3e-expansion-header-font-size`                | Font size of the header text.                       |
| `--m3e-expansion-header-font-weight`              | Font weight of the header text.                     |
| `--m3e-expansion-header-line-height`              | Line height of the header text.                     |
| `--m3e-expansion-header-tracking`                 | Letter spacing of the header text.                  |
| `--m3e-expansion-panel-text-color`                | Color of the panel's text content.                  |
| `--m3e-expansion-panel-disabled-text-color`       | Color of the panel's text content, when disabled.   |
| `--m3e-expansion-panel-disabled-text-opacity`     | Opacity of the panel's text content, when disabled. |
| `--m3e-expansion-panel-container-color`           | Background color of the panel container.            |
| `--m3e-expansion-panel-elevation`                 | Elevation level when collapsed.                     |
| `--m3e-expansion-panel-shape`                     | Shape (e.g. border radius) when collapsed.          |
| `--m3e-expansion-panel-open-elevation`            | Elevation level when expanded.                      |
| `--m3e-expansion-panel-open-shape`                | Shape (e.g. border radius) when expanded.           |
| `--m3e-expansion-panel-content-padding`           | Padding around the content area.                    |
| `--m3e-expansion-panel-actions-spacing`           | Spacing between action buttons/elements.            |
| `--m3e-expansion-panel-actions-padding`           | Padding around the actions section.                 |
| `--m3e-expansion-panel-actions-divider-thickness` | Thickness of the divider above actions.             |
| `--m3e-expansion-panel-actions-divider-color`     | Color of the divider above actions.                 |

## 🤝 Contributing

See the root monorepo `CONTRIBUTING.md` for guidelines on contributing to this package.

## 📄 License

This package is licensed under the MIT License.