@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 monorepo, a unified suite of Material 3 web components. Explore the docs to see them in action.

📦 Installation

npm install @m3e/expansion-panel

💻 Editor Integration

This package includes a 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 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:

{
  "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. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/expansion-panel/dist/index.js"></script>

In addition, you must use an import map to include dependencies.

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/[email protected]/+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.

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