@m3e/slider

The m3e-slider component enables users to select a numeric value from a continuous or discrete range. Designed according to Material 3 principles, it supports labeled value indicators, tick marks, and snapping behavior.

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/slider

💻 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/slider, 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/slider/dist/html-custom-data.json"],
  "css.customData": ["./node_modules/@m3e/slider/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/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/[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-slider — Allows for the selection of numeric values from a range.
• m3e-slider-thumb — A thumb used to select a value in a slider.

🧪 Examples

The following example illustrates a labelled slider with thumb used to select a single numeric value.

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

The next example illustrates a labelled range slider with two thumbs used to select a minimum and maximum numeric value.

<m3e-slider labelled>
  <m3e-slider-thumb value="25"></m3e-slider-thumb>
  <m3e-slider-thumb value="75"></m3e-slider-thumb>
</m3e-slider>

📖 API Reference

🗂️ Slider

This section details the attributes, events and CSS custom properties available for the m3e-slider component.

⚙️ Attributes

| Attribute | Type | Default | Description | | ---------- | ------------------------------------------------------------------ | --------------- | -------------------------------------------- | | disabled | boolean | false | Whether the element is disabled. | | discrete | boolean | false | Whether to show tick marks. | | labelled | boolean | false | Whether to show value labels when activated. | | min | number | 0 | The minimum allowable value. | | max | number | 100 | The maximum allowable value. | | step | number | 1 | The value at which the thumb will snap. | | size | "extra-small", "small", "medium", "large", "extra-large" | "extra-small" | The size of the slider. |

🔔 Events

| Event | Description | | -------- | ------------------------------- | | input | Emitted when the value changes. | | change | Emitted when the value changes. |

🎛️ CSS Custom Properties

| Property | Description | | ------------------------------------------------------------ | ----------------------------------------------------------------- | | --m3e-slider-min-width | Minimum inline size of the slider host. | | --m3e-slider-small-height | Height of the slider when size is small or extra-small. | | --m3e-slider-medium-height | Height of the slider when size is medium. | | --m3e-slider-large-height | Height of the slider when size is large. | | --m3e-slider-extra-large-height | Height of the slider when size is extra-large. | | --m3e-slider-small-active-track-shape | Corner shape of the active track for small sliders. | | --m3e-slider-small-inactive-active-track-start-shape | Corner shape of the inactive track start for small sliders. | | --m3e-slider-small-inactive-track-end-shape | Corner shape of the inactive track end for small sliders. | | --m3e-slider-medium-active-track-shape | Corner shape of the active track for medium sliders. | | --m3e-slider-medium-inactive-active-track-start-shape | Corner shape of the inactive track start for medium sliders. | | --m3e-slider-medium-inactive-track-end-shape | Corner shape of the inactive track end for medium sliders. | | --m3e-slider-large-active-track-shape | Corner shape of the active track for large sliders. | | --m3e-slider-large-inactive-active-track-start-shape | Corner shape of the inactive track start for large sliders. | | --m3e-slider-large-inactive-track-end-shape | Corner shape of the inactive track end for large sliders. | | --m3e-slider-extra-large-active-track-shape | Corner shape of the active track for extra-large sliders. | | --m3e-slider-extra-large-inactive-active-track-start-shape | Corner shape of the inactive track start for extra-large sliders. | | --m3e-slider-extra-large-inactive-track-end-shape | Corner shape of the inactive track end for extra-large sliders. | | --m3e-slider-extra-small-track-height | Height of the track for extra-small sliders. | | --m3e-slider-small-track-height | Height of the track for small sliders. | | --m3e-slider-medium-track-height | Height of the track for medium sliders. | | --m3e-slider-large-track-height | Height of the track for large sliders. | | --m3e-slider-extra-large-track-height | Height of the track for extra-large sliders. | | --m3e-slider-tick-size | Size of each tick mark. | | --m3e-slider-tick-shape | Corner shape of each tick mark. | | --m3e-slider-inactive-track-color | Background color of the inactive track when enabled. | | --m3e-slider-disabled-inactive-track-color | Base color of the inactive track when disabled. | | --m3e-slider-disabled-inactive-track-opacity | Opacity of the inactive track when disabled. | | --m3e-slider-active-track-color | Background color of the active track when enabled. | | --m3e-slider-disabled-active-track-color | Base color of the active track when disabled. | | --m3e-slider-disabled-active-track-opacity | Opacity of the active track when disabled. | | --m3e-slider-tick-active-color | Color of active ticks when enabled. | | --m3e-slider-disabled-tick-active-color | Color of active ticks when disabled. | | --m3e-slider-tick-inactive-color | Color of inactive ticks when enabled. | | --m3e-slider-disabled-tick-inactive-color | Color of inactive ticks when disabled. |

🗂️ Slider Thumb

This section details the attributes, events and CSS custom properties available for the m3e-slider-thumb component.

⚙️ Attributes

| Attribute | Type | Default | Description | | ---------- | ------------------ | ------- | ------------------------------------------------------------------------- | | disabled | boolean | false | Whether the element is disabled. | | name | string | | The name that identifies the element when submitting the associated form. | | value | number | null | null | The value of the thumb. |

🔔 Events

| Event | Description | | -------- | ------------------------------- | | input | Emitted when the value changes. | | change | Emitted when the value changes. |

🎛️ CSS Custom Properties

| Property | Description | | ------------------------------------- | ---------------------------------------------- | | --m3e-slider-thumb-width | Width of the slider thumb. | | --m3e-slider-thumb-padding | Horizontal padding around the thumb. | | --m3e-slider-thumb-color | Active color of the slider thumb when enabled. | | --m3e-slider-thumb-pressed-width | Width of the thumb when pressed. | | --m3e-slider-thumb-disabled-color | Color of the thumb when disabled. | | --m3e-slider-thumb-disabled-opacity | Opacity of the thumb when disabled. | | --m3e-slider-label-width | Width of the floating label above the thumb. | | --m3e-slider-label-container-color | Background color of the label container. | | --m3e-slider-label-color | Text color of the label. | | --m3e-slider-label-font-size | Font size of the label text. | | --m3e-slider-label-font-weight | Font weight of the label text. | | --m3e-slider-label-line-height | Line height of the label text. | | --m3e-slider-label-tracking | Letter spacing of the label text. |

🤝 Contributing

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

📄 License

This package is licensed under the MIT License.