Slider

lightning-slider

An input range slider for specifying a value between two specified numbers.

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="slider" model="lwc" namespace="lightning"}

:::::

:::::tab

A lightning-slider component is a horizontal or vertical slider for specifying a value between two specified numbers. For example, this slider can be used to capture user input about order quantity or when you want to use an input field of type="range". To orient the slider vertically, set type="vertical". Older browsers that don't support the slider fallback and treat it as type="text".

Here's an example of a slider with a step increment of 10.

<template>
    <lightning-slider
        label="Volume"
        step="10"
        value={myValue}
        onchange={handleChange}
    >
    </lightning-slider>
    <div class="slds-m-vertical_medium">
        <p>
            The value of the slider is:
            <span class="slds-text-heading_small">{myValue}</span>
        </p>
    </div>
</template>

Handle the change event and get the slider value by using the event.detail property.

import { LightningElement } from "lwc";

export default class SliderExample extends LightningElement {
  myValue = 20; //initial value

  handleChange(event) {
    this.myValue = event.detail.value;
  }
}

Design

lightning-slider implements the slider blueprint in the Salesforce Lightning Design System (SLDS). The slider adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

Input Validation

Client-side input validation is available for this component. Note that a disabled slider is always valid.

To programmatically show error messages on invalid fields, use the reportValidity() method. For custom validity error messages, specify the message using setCustomValidity() and reportValidity().

For more information, see the lightning-input documentation.

Component Styling

Use a combination of variants, sizes, positioning type, and utility classes to customize the slider.

Variants

Specify the variant attribute with one of these values.

• standard is the default variant, which includes the text label before the range values and slider
• label-hidden hides the text label from view

Sizes

Specify the size attribute with one of these values.

• x-small takes up a width of 192px
• small takes up a width of 240px
• medium takes up a width of 320px
• largetakes up a width of 400px

The default slider size takes up the width of the view port.

Positioning Type

Specify the type attribute with one of these attributes.

• horizontal is the default position type, which places the slider horizontally across the view port
• vertical places the slider vertically with a height of 192px

Utility Classes

To apply additional styling, use the SLDS utility classes with the class attribute.

This example adds padding above the slider using an SLDS class.

<div class="slds-p-top_large">
    <lightning-slider label="Volume" step="10" value="20"> </lightning-slider>
</div>

Styling Hooks

Component styling hooks provide CSS custom properties that use the --slds-c-* prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the SLDS 1 component blueprints for available component styling hooks.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

Customize Units and Number Formatting

By default, the slider displays the range after the label as min-max, such as 0-100, and the current value as a plain number. To customize how the range and value appear on the slider, use these attributes:

• unit defines a unit label that annotates the range display and value readout, such as %. The default is an empty string, which shows the plain range and value with no unit.
• unit-position sets the placement of the unit relative to the range and value. Valid values include suffix (default) or prefix.
• format-number is a formatter function that converts each range endpoint and the value readout to text, replacing the built-in formatting. The default is undefined.
• minimum-fraction-digits is the minimum number of fractional digits for the range endpoints and value readout, acting as a floor on the step-derived precision. The default is 0.

These attributes changes the range and value labels only. The numeric value that you get from the change event remains the same. The next section describes each attribute with examples.

unit

To annotate both the range and the value readout with a unit label, specify the unit attribute. The unit can be any string, such as a symbol (%, $, °C) or an abbreviation (MB).

The string unit is used exactly as provided, so include a leading space if you want to separate the unit from the number, such as unit=" pts".

This example displays the range as 0-100% and a value of 50 as 50%.

<template>
    <lightning-slider label="Volume" value="50" unit="%"> </lightning-slider>
</template>

unit-position

To control where the unit appears relative to the number, specify the unit-position attribute with these values:

• suffix places the unit after the number, such as 50%. suffix is the default.
• prefix places the unit before the number, such as $50. Use prefix for currency symbols, if the symbol must appear before the number.

This example displays the range as $0-500 and a value of 250 as $250.

<template>
    <lightning-slider
        label="Price"
        min="0"
        max="500"
        value="250"
        unit="$"
        unit-position="prefix"
    >
    </lightning-slider>
</template>

minimum-fraction-digits

To set the minimum number of digits to display after the decimal point, specify the minimum-fraction-digits attribute. The effective number of decimal places is the greater of the minimum-fraction digits and the step attribute. Use minimum-fraction-digits to force a consistent decimal display, such as for a decimal field whose step is a whole number.

When you set minimum-fraction-digits to a value greater than 0, the range display becomes asymmetric; the minimum endpoint stays bare and the maximum endpoint carries the decimals. This example displays the range as 0-1500.0 and a value of 1500 as 1,500.0.

<template>
    <lightning-slider
        label="Amount"
        min="0"
        max="1500"
        value="1500"
        minimum-fraction-digits="1"
    >
    </lightning-slider>
</template>

A finer step takes precedence over the floor. For example, with step="0.05" and minimum-fraction-digits="1", the maximum reads with two decimal places, such as 0-1.00.

format-number

The format-number attribute takes a formatter function with the signature (numericValue) => string. The function provides the number-to-text conversion for each range endpoint and for the value readout, replacing the slider's built-in step-precision formatting. Any unit and unit-position decoration is then applied around the function's output. Use format-number to inject domain- or locale-specific formatting, such as compact currency, without teaching the slider about currencies or locales.

Because format-number is a function rather than a string, bind it as a property with the {} syntax instead of a static attribute value.

<template>
    <lightning-slider
        label="Budget"
        min="0"
        max="1000000"
        value="250000"
        format-number={currencyFormatter}
    >
    </lightning-slider>
</template>

Define the formatter in your JavaScript. This example uses Intl.NumberFormat with compact notation to render a value of 250000 as $250K, with the range showing $0-$1M.

import { LightningElement } from "lwc";

export default class SliderExample extends LightningElement {
  currencyFormatter = (value) =>
    new Intl.NumberFormat("en-US", {
      style: "currency",
      currency: "USD",
      notation: "compact",
      maximumFractionDigits: 1,
    }).format(value);
}

If you combine format-number with unit, the unit decorates the formatter's output. For example, a formatter that returns #50 with unit=" pts" produces #50 pts.

Usage Considerations

Use the change event to detect changes to the slider value instead of the blur event. Browsers such as Safari don't give focus to the slider so the blur event doesn't fire.

By default, the min and max values are 0 and 100, but you can specify your own values. If you specify your own step increment value, you can drag the slider based on the step increment only. If you set the value lower than the min value, then the value is set to the min value. Similarly, setting the value higher than the max value results in the value being set to the max value.

For precise numerical values, we recommend using the lightning-input component of type="number" instead.

:::::

:::::tab ::component-specification{component="slider" model="lwc" namespace="lightning"}

:::::

::::::