npm package: @m3e/slide-group
Description: Slide Group for M3E
Author: matraic
Latest version: 1.3.1
Deprecated: Deprecated — use @m3e/web instead.

# @m3e/slide-group

The `m3e-slide-group` component presents directional pagination controls for navigating overflowing content. It orchestrates scrollable layouts with expressive slot-based icons and adaptive orientation, revealing navigation affordances only when content exceeds a defined threshold. It supports both horizontal and vertical flows, and encodes accessibility through customizable labels and interaction states.

> **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/slide-group
```

## 💻 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/slide-group`, 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/slide-group/dist/html-custom-data.json"],
  "css.customData": ["./node_modules/@m3e/slide-group/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/slide-group/dist/index.js"></script>
```

You also need a module script for `@m3e/icon-button` due to it being a dependency.

```html
<script type="module" src="/node_modules/@m3e/icon-button/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-slide-group` — Presents pagination controls used to scroll overflowing content.

## 🧪 Examples

- The following example illustrates a horizontally scrollable group of items with directional pagination buttons.
  The scroll controls appear when content exceeds the `48px` threshold.

```html
<m3e-slide-group threshold="48">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
  <div>Item 5</div>
</m3e-slide-group>
```

## 📖 API Reference

This section details the attributes, slots and CSS custom properties available for the `m3e-slide-group` component.

### ⚙️ Attributes

| Attribute             | Type      | Default           | Description                                                                                        |
| --------------------- | --------- | ----------------- | -------------------------------------------------------------------------------------------------- |
| `disabled`            | `boolean` | `false`           | Whether scroll buttons are disabled.                                                               |
| `next-page-label`     | `string`  | `"Next page"`     | The accessible label given to the button used to move to the previous page.                        |
| `previous-page-label` | `string`  | `"Previous page"` | The accessible label given to the button used to move to the next page.                            |
| `threshold`           | `number`  | `0`               | A value, in pixels, indicating the scroll threshold at which to begin showing pagination controls. |
| `vertical`            | `boolean` | `false`           | Whether content is oriented vertically.                                                            |

#### 🧩 Slots

| Slot        | Description                                          |
| ----------- | ---------------------------------------------------- |
| _(default)_ | Renders the content to paginate.                     |
| `next-icon` | Renders the icon to present for the next button.     |
| `prev-icon` | Renders the icon to present for the previous button. |

### 🎛️ CSS Custom Properties

| Property                             | Description                                                                   |
| ------------------------------------ | ----------------------------------------------------------------------------- |
| `--m3e-slide-group-button-icon-size` | Sets icon size for scroll buttons; overrides default small icon size.         |
| `--m3e-slide-group-button-size`      | Defines scroll button size; used for width (horizontal) or height (vertical). |
| `--m3e-slide-group-divider-top`      | Adds top border to content container for visual separation.                   |
| `--m3e-slide-group-divider-bottom`   | Adds bottom border to content container for visual separation.                |

## 🤝 Contributing

See the root monorepo `CONTRIBUTING.md` for guidelines on contributing to this package.

## 📄 License

This package is licensed under the MIT License.