> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/slider.md).

# Slider

`avonni-slider`

Lets users select a value, or a range of values, by dragging one or more handles along a track.

## Overview

**Slider** is a Lightning Web Component that lets users select a number—or a range—by dragging one or more thumbs along a track.

Use it in your own Lightning Web Components to capture values like volume, budget, completion, or price ranges. You control the bounds, step, orientation, unit formatting, tick marks, pin, and single- or multi-thumb behavior—all through the component's attributes—and read the result from the `change` event.

### Use Cases

* **Settings:** Adjust a value such as volume or brightness.
* **Budgets and amounts:** Pick a currency value with formatted display.
* **Completion and ratios:** Capture a percentage between 0 and 1.
* **Price ranges:** Select a min/max range with two thumbs.
* **Filters:** Constrain results to a numeric window.

***

## Unit Guidelines

| Unit       | Use Case                                                   |
| ---------- | ---------------------------------------------------------- |
| `decimal`  | Plain numbers such as counts or levels (default).          |
| `currency` | Monetary amounts; set `currencyCode` in `unit-attributes`. |
| `percent`  | Ratios; pass a 0–1 value with `isFormatted`.               |
| `custom`   | Labeled stops via `customLabels` in `unit-attributes`.     |

***

## Use Case Examples

### Example 1: Single-value slider with a pin

**Scenario:** Let a user adjust a volume level and react to changes.

```html
<!-- volumeControl.html -->
<template>
    <avonni-slider
        label="Volume"
        min="0"
        max="100"
        step="5"
        value={volume}
        unit="decimal"
        show-pin
        size="medium"
        onchange={handleChange}
    ></avonni-slider>
</template>
```

```js
// volumeControl.js
import { LightningElement } from 'lwc';

export default class VolumeControl extends LightningElement {
    volume = 40;

    handleChange(event) {
        this.volume = event.detail.value; // the new value
    }
}
```

**Result:** A medium slider from 0 to 100 in steps of 5 that shows a value pin while dragging and fires `change` with the new value.

### Example 2: Range slider with two thumbs

**Scenario:** Capture a price range using two thumbs that cannot cross.

```html
<!-- priceFilter.html -->
<template>
    <avonni-slider
        label="Price range"
        min="0"
        max="100"
        step="1"
        value={priceRange}
        unit="currency"
        unit-attributes={currencyAttributes}
        disable-swap
        minimum-distance="10"
        size="large"
        onchange={handleChange}
    ></avonni-slider>
</template>
```

```js
// priceFilter.js
import { LightningElement } from 'lwc';

export default class PriceFilter extends LightningElement {
    priceRange = [20, 80];
    currencyAttributes = {
        currencyCode: 'USD',
        currencyDisplayAs: 'symbol',
        maximumFractionDigits: 0
    };

    handleChange(event) {
        this.priceRange = event.detail.value; // [min, max]
    }
}
```

**Result:** A two-thumb slider showing a currency-formatted range; the thumbs stay at least 10 apart and can't swap, and `change` fires with `[min, max]`.

***

## Specifications

### Attributes

| Name                           | Description                                                                                                                                     | Type                       | Default        | Required |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | -------------- | -------- |
| `alternative-text`             | The assistive text for the input.                                                                                                               | String                     | —              |          |
| `disable-swap`                 | If present, the slider thumbs can't swap order.                                                                                                 | Boolean                    | `false`        |          |
| `disabled`                     | If present, the slider is disabled and users cannot interact with it.                                                                           | Boolean                    | `false`        |          |
| `hide-min-max-values`          | If present, min and max value indicators are removed.                                                                                           | Boolean                    | `false`        |          |
| `hide-track`                   | If present, track is removed.                                                                                                                   | Boolean                    | `false`        |          |
| `label`                        | Text label to describe the slider. Provide your own label to describe the slider.                                                               | String                     | —              |          |
| `max`                          | The maximum value of the input slider.                                                                                                          | Number                     | `100`          |          |
| `message-when-range-overflow`  | Error message to be displayed when a range overflow is detected.                                                                                | String                     | —              |          |
| `message-when-range-underflow` | Error message to be displayed when a range underflow is detected.                                                                               | String                     | —              |          |
| `message-when-step-mismatch`   | Error message to be displayed when a step mismatch is detected.                                                                                 | String                     | —              |          |
| `min`                          | The minimum value of the input slider.                                                                                                          | Number                     | `0`            |          |
| `minimum-distance`             | The minimum distance between nodes when swap is disabled and there are many nodes.                                                              | Number                     | `0`            |          |
| `show-pin`                     | If present, a pin containing the value is shown when the thumb is pressed.                                                                      | Boolean                    | `false`        |          |
| `show-tick-marks`              | If present, minor tick marks are displayed at every step.                                                                                       | Boolean                    | `false`        |          |
| `size`                         | Size of the slider. Accepted values are responsive, x-small, small, medium, and large.                                                          | String                     | `"responsive"` |          |
| `step`                         | The step increment value of the input slider. Example steps include 0.1, 1, or 10.                                                              | Number                     | `1`            |          |
| `tick-mark-style`              | If present, tick marks are displayed with the according style. Accepted styles are inner-tick, tick, dot.                                       | String                     | `"inner-tick"` |          |
| `type`                         | The type determines the orientation of the slider. Accepted values are vertical and horizontal.                                                 | String                     | `"horizontal"` |          |
| `unit`                         | Format the value displayed. Accepted units include decimal, currency, percent and custom. See Units and Unit Attributes table for more details. | String                     | `"decimal"`    |          |
| `unit-attributes`              | Attributes specific to the selected unit. See Units and Unit Attributes table for more details.                                                 | AvonniSliderUnitAttributes | —              |          |
| `validity`                     | Represents the validity states that an element can be in, with respect to constraint validation.                                                | Object                     | —              |          |
| `value`                        | The value of the slider. If multiple values are given, slider will have multiple thumbs, one for each value.                                    | number                     | number\[]      | `50`     |
| `variant`                      | The variant changes the appearance of the slider. Accepted variants include standard and label-hidden. The default is standard.                 | String                     | `"standard"`   |          |

### Methods

| Name                       | Description                                                                                                                                              | Argument Name | Argument Type | Argument Description                                                                            |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------- | ----------------------------------------------------------------------------------------------- |
| `blur`                     | Removes keyboard focus from the input element.                                                                                                           |               |               |                                                                                                 |
| `checkValidity`            | Checks if the input is valid.                                                                                                                            |               |               |                                                                                                 |
| `focus`                    | Sets focus on the next input element.                                                                                                                    |               |               |                                                                                                 |
| `reportValidity`           | Displays the error messages. If the input is valid, reportValidity() clears displayed error messages.                                                    |               |               |                                                                                                 |
| `setCustomValidity`        | Sets a custom error message to be displayed when a form is submitted.                                                                                    | `message`     | String        | The string that describes the error. If message is an empty string, the error message is reset. |
| `showHelpMessageIfInvalid` | Displays error messages on invalid fields. An invalid field fails at least one constraint validation and returns false when `checkValidity()` is called. |               |               |                                                                                                 |

### Custom Events

#### `blur`

The event fired when the focus is removed from the slider.

The `blur` event doesn't return any parameters.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

#### `change`

The event fired when the slider value changed.

The `change` event returns the following parameters.

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `value`   | number | number\[]   |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

#### `focus`

The event fired when the focus is set on the slider.

The `focus` event doesn't return any parameters.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

### Styling Hooks

| CSS Variable                                   | Type   | Default               |
| ---------------------------------------------- | ------ | --------------------- |
| `--avonni-slider-header-text-color`            | color  | `#080707`             |
| `--avonni-slider-header-font-size`             | font   | `0.75rem`             |
| `--avonni-slider-header-font-style`            | font   | `normal`              |
| `--avonni-slider-header-font-weight`           | font   | `400`                 |
| `--avonni-slider-pin-color-background`         | color  | `#1a5296`             |
| `--avonni-slider-pin-radius`                   | radius | `2rem`                |
| `--avonni-slider-pin-text-color`               | color  | `#ffffff`             |
| `--avonni-slider-thumb-color`                  | color  | `#0176d3`             |
| `--avonni-slider-thumb-color-hover`            | color  | `#014486`             |
| `--avonni-slider-thumb-color-active`           | color  | `#014486`             |
| `--avonni-slider-thumb-radius`                 | radius | `0.5rem`              |
| `--avonni-slider-thumb-shadow-focus`           | color  | `0 0 3px 1px #99d3ff` |
| `--avonni-slider-thumb-sizing-width`           | radius | `8px`                 |
| `--avonni-slider-track-color`                  | color  | `#0176d3`             |
| `--avonni-slider-track-color-background`       | color  | `#ecebea`             |
| `--avonni-slider-track-sizing-height`          | size   | `4px`                 |
| `--avonni-slider-track-radius`                 | radius | `0.5rem`              |
| `--avonni-slider-unit-custom-sizing-min-width` | size   | `3rem`                |
| `--avonni-slider-unit-custom-sizing-max-width` | size   | `6rem`                |
| `--avonni-slider-unit-custom-line-clamp`       | number | `1`                   |
| `--avonni-slider-unit-text-color`              | color  | `#3e3e3c`             |
| `--avonni-slider-unit-font-size`               | font   | `0.75rem`             |
| `--avonni-slider-unit-font-style`              | font   | `normal`              |
| `--avonni-slider-unit-font-weight`             | font   | `400`                 |

## Key Considerations

* **Single vs range:** Pass a number for one thumb or an array for a multi-thumb range slider.
* **Step alignment:** `value` should align with `step`; mismatches can trigger a step-mismatch validation message.
* **Unit formatting:** Pair `unit` with `unit-attributes` (currency code, custom labels) for the right display.
* **Range constraints:** Use `disable-swap` and `minimum-distance` to keep range thumbs in order and apart.
* **Reading values:** The `change` detail's `value` is a number for single sliders and an array for ranges.
* **Best Practice:** Set `min`, `max`, and `step` to match your data, and choose a `unit` (with matching `unit-attributes`) so the displayed value reads naturally.

***

## Troubleshooting Common Issues

* **Thumb won't move:** Confirm the slider is not `disabled` and the value sits within `min`–`max`.
* **Value not formatted:** Set `unit` and supply the matching `unit-attributes` (e.g. `currencyCode` for `currency`).
* **Range thumbs jump past each other:** Set `disable-swap` and a `minimum-distance` to keep them ordered.
* **If issues persist:** Contact our support team at <support@avonni.app> for assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/lwc-components/core-components/slider.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.