@m3e/button-group

The m3e-button-group component arranges multiple into a unified, expressive layout, supporting both standard and connected variants. It enables seamless, accessible grouping of actions, adapts to various sizes, and ensures consistent spacing, shape, and alignment. Designed according to Material 3 principles, it empowers users to interact with related actions in a visually harmonious and intuitive way.

> This package is part of M3E monorepo, a unified suite of Material 3 web components. Explore the docs to see them in action.

📦 Installation

``bash
npm install @m3e/button-group
`

💻 Editor Integration

This package includes a Custom Elements Manifest to support enhanced editor tooling and developer experience.

$3

To enable autocomplete and hover documentation for @m3e/button-group, 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:

`json
{
"html.customData": ["./node_modules/@m3e/button-group/dist/html-custom-data.json"],
"css.customData": ["./node_modules/@m3e/button-group/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.

`html

`

You also need a module script for @m3e/button and @m3e/icon-button due to being a dependency.

`html


`

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

`html

`

> For production, use index.min.js for faster load times.

🗂️ Elements

- m3e-button-group — Organizes buttons and adds interactions between them.

🧪 Examples

The following example illustrates a standard button group.

`html





`

The next example illustrates a connected button group.

`html

Start
Directions
Share

`

📖 API Reference

This section details the attributes, slots, and CSS custom properties available for the m3e-button-group component.

$3

| Attribute | Type | Default | Description |
| --------- | ------------------------------------------------------------------ | ------------ | ------------------------------------------------ |
| multi | boolean | false | Whether multiple toggle buttons can be selected. |
| size | "extra-small" \| "small" \| "medium" \| "large" \| "extra-large" | "small" | The size of the group. |
| variant | "standard" \| "connected" | "standard" | The appearance variant of the group. |

$3

| Slot | Description |
| ----------- | --------------------------------- |
| _(default)_ | Renders the buttons of the group. |

$3

| Property | Description |
| -------------------------------------------------------------- | ------------------------------------------------- |
| --m3e-standard-button-group-extra-small-spacing | Spacing between buttons in standard, extra-small. |
| --m3e-standard-button-group-small-spacing | Spacing between buttons in standard, small. |
| --m3e-standard-button-group-medium-spacing | Spacing between buttons in standard, medium. |
| --m3e-standard-button-group-large-spacing | Spacing between buttons in standard, large. |
| --m3e-standard-button-group-extra-large-spacing | Spacing between buttons in standard, extra-large. |
| --m3e-connected-button-group-spacing | Spacing between buttons in connected variant. |
| --m3e-connected-button-group-extra-small-inner-shape | Corner shape for connected, extra-small. |
| --m3e-connected-button-group-extra-small-inner-pressed-shape | Pressed corner shape for connected, extra-small. |
| --m3e-connected-button-group-small-inner-shape | Corner shape for connected, small. |
| --m3e-connected-button-group-small-inner-pressed-shape | Pressed corner shape for connected, small. |
| --m3e-connected-button-group-medium-inner-shape | Corner shape for connected, medium. |
| --m3e-connected-button-group-medium-inner-pressed-shape | Pressed corner shape for connected, medium. |
| --m3e-connected-button-group-large-inner-shape | Corner shape for connected, large. |
| --m3e-connected-button-group-large-inner-pressed-shape | Pressed corner shape for connected, large. |
| --m3e-connected-button-group-extra-large-inner-shape | Corner shape for connected, extra-large. |
| --m3e-connected-button-group-extra-large-inner-pressed-shape | Pressed corner shape for connected, extra-large. |

🤝 Contributing

See the root monorepo CONTRIBUTING.md` for guidelines on contributing to this package.

📄 License

This package is licensed under the MIT License.