The m3e-paginator component is a compact, accessible paginator control for navigating paged data sets. It provides semantic first/previous/next/last navigation controls and an optional page-size selector.

import "@m3e/web/paginator";

This section outlines usage examples and configuration guidance for the components in this package.

At minimum, you must specify the total number of items being paged and the page size. Use the length and page-size attributes of the m3e-paginator component, respectively. By default, page-size is set to 50.

When a user interacts with the paginator, it emits a page event. This event can be used to update any associated data view and includes the following properties:

• pageIndex: number — The zero-based index of the current page.
• previousPageIndex: number (optional) — The zero-based index of the previously selected page.
• pageSize: number | "all" — The current page size.
• length: number — The total number of items being paged.

<m3e-paginator length="100"></m3e-paginator>

The page-sizes attribute lets you define which page size options are available to users. It accepts a comma-separated list of values and may include "all". By default, page-sizes is set to "5,10,25,50,100".

The current page-size will always appear in the dropdown, event if its not included in page-sizes.

When page-size is set to "all", the range label and navigation actions are hidden.

<m3e-paginator length="100" page-sizes="10,50,all" page-size="all"></m3e-paginator>

By default, the first and last page buttons are hidden. Use the show-first-last-buttons attribute to show them.

<m3e-paginator length="100" show-first-last-buttons></m3e-paginator>

Paginators are density-aware and adjust their vertical spacing based on the --md-sys-density-scale and --md-sys-density-size custom CSS properties. The default density size is 4dp (0.25rem). Paginators support negative density scales down to -3, with each step reducing the visual height by one density unit. The internal form field accepts compact densities (-3 and -2) and ignores larger values.

The following illustrates applying -3 density to a paginator.

<m3e-paginator class="density-3" length="100" show-first-last-buttons></m3e-paginator>

.density-3 {
  --md-sys-density-scale: -3;
}

The paginator uses ARIA role="group" to semantically group its child controls. You must add an aria-label or aria-labelledby attribute to each m3e-paginator with a label that describes the content controlled by the pagination control.

You can use the first-page-label, previous-page-label, next-page-label, and last-page-label attributes to change the accessible labels of navigation actions.

The @m3e/web 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/web/dist/paginator.js"></script>

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

<script type="importmap">
  {
    "imports": {
      "tslib": "https://cdn.jsdelivr.net/npm/tslib@2.8.1/+esm",
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "lit/": "https://cdn.jsdelivr.net/npm/lit@3.3.0/",
      "lit-html": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/+esm",
      "lit-html/directive.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directive.js",
      "lit-html/directives/if-defined.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/if-defined.js",
      "lit-html/directives/class-map.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/class-map.js",
      "@lit/reactive-element": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/+esm",
      "@lit/reactive-element/": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/",
      "@m3e/web/core": "/node_modules/@m3e/web/dist/core.js",
      "@m3e/web/core/a11y": "/node_modules/@m3e/web/dist/core-a11y.js",
      "@m3e/web/core/anchoring": "/node_modules/@m3e/web/dist/core-anchoring.js",
      "@m3e/web/core/bidi": "/node_modules/@m3e/web/dist/core-bidi.js",
      "@m3e/web/core/platform": "/node_modules/@m3e/web/dist/core-platform.js",
      "@m3e/web/form-field": "/node_modules/@m3e/web/dist/form-field.js",
      "@m3e/web/select": "/node_modules/@m3e/web/dist/select.js",
      "@m3e/web/option": "/node_modules/@m3e/web/dist/option.js",
      "@m3e/web/icon-button": "/node_modules/@m3e/web/dist/icon-button.js",
      "@m3e/web/tooltip": "/node_modules/@m3e/web/dist/tooltip.js"
    }
  }
</script>

For production builds, use the minified files to ensure optimal load performance.

The @m3e/web package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.