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

📦 Installation

npm install @m3e/slide-group

💻 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/slide-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:

{
  "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. 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/slide-group/dist/index.js"></script>

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

<script type="module" src="/node_modules/@m3e/icon-button/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-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.

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