The m3e-slider component enables users to select a numeric value from a continuous or discrete range.

npm i @m3e/slider

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

The m3e-slider allows for the selection of a value from a range similar to <input type="range">. They require a m3e-slider-thumb, which is responsible for rendering the interactive handle, managing pointer and keyboard input, and conveying current value semantics

<m3e-slider>
  <m3e-slider-thumb></m3e-slider-thumb>
</m3e-slider>

By default the minimum value of the slider is 0, the maximum value is 100, and the thumb moves in increments of 1. These values can be changed by setting the min, max, and step attributes respectively.

The thumb value is set to the minimum value unless otherwise specified using the value attribute of the m3e-slider-thumb. When changed through user interaction, a cancellable input event is emitted followed by a change event. To cancel value change, call preventDefault during input.

<m3e-slider min="1" max="5" step="0.5">
  <m3e-slider-thumb value="1.5"></m3e-slider-thumb>
</m3e-slider>

A m3e-slider can be converted into a range slider by specifying two thumbs.

<m3e-slider>
  <m3e-slider-thumb value="20"></m3e-slider-thumb>
  <m3e-slider-thumb value="80"></m3e-slider-thumb>
</m3e-slider>

Negative value ranges are supported by setting the min attribute to a negative value.

<m3e-slider min="-50">
  <m3e-slider-thumb value="-20"></m3e-slider-thumb>
</m3e-slider>

There are five size variants which can be used to add or remove emphasis: extra-small (default), small, medium, large, and extra-large. Use the size attribute to control a slider's size.

<m3e-slider size="extra-small">
  <m3e-slider-thumb value="20"></m3e-slider-thumb>
</m3e-slider>
<!-- Additional sizes omitted for brevity -->

Use the labelled attribute of a m3e-slider to control whether to show thumb labels. By default, the value of a thumb is used as the label text. You can control label formatting by setting the displayWith property to a function that returns a label given a value.

<m3e-slider labelled>
  <m3e-slider-thumb value="20"></m3e-slider-thumb>
</m3e-slider>

By default, tick marks are not presented. Use the discrete attribute to show them. You must also specify a step larger than 1 for tick marks to show.

<m3e-slider discrete step="10">
  <m3e-slider-thumb value="20"></m3e-slider-thumb>
</m3e-slider>

Sliders can be disabled using the disabled attribute. If labelled, thumb labels are shown on hover.

<m3e-slider labelled disabled>
  <m3e-slider-thumb value="20"></m3e-slider-thumb>
</m3e-slider>

While uncommon, individual thumbs can also be disabled while allowing another thumb to be enabled.

<m3e-slider labelled>
  <m3e-slider-thumb value="20"></m3e-slider-thumb>
  <m3e-slider-thumb disabled value="80"></m3e-slider-thumb>
</m3e-slider>

Sliders are not given an ARIA role, indicating that they are treated as neutral, non-semantic elements in the accessibility tree unless explicitly referenced or annotated.

Thumbs are given ARIA role="slider" indicating that each functions as an independent value selector within the range, conveying its current position via aria-valuemin, aria-valuemax, and aria-valuenow attributes.

When disabled, aria-disabled is used to convey to assistive technologies that a thumbs are present but intentionally non-interactive.

Always provide an accessible label via aria-label or aria-labelledby for each thumb.

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/slider/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/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
    }
  }
</script>

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

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