# Range Slider

> A Range Slider widget with two thumbs on one track, to pick a low and a high value such as a price range

Range Slider widgets are [Input Fields](https://golemui.com/dx/widgets-reference/input-fields/overview.md) with two thumbs on one track, to pick a low and a high value, such as a price range. The thumbs can meet but not cross, and a press on the track moves the nearer thumb there.


```ts title="range-slider.ts"

export default [
  gui.inputs.rangeSlider('price', {
    maximum: 500,
    step: 10,
    format: {
      style: 'currency',
      currency: 'EUR',
      maximumFractionDigits: 0,
    },
    label: 'Price per night',
    defaultValue: {
      start: 100,
      end: 300,
    },
  }),
];
```

_Live demo on the docs page. Form definition: [range-slider.ts](https://golemui.com/template/widgets-dx/range-slider/range-slider.ts)._

The value is one object, `{ start, end }`, with two numbers. It is not an array, as the date and time ranges are. Without a `defaultValue`, the range slider has no value until the user moves a thumb. A key or a press that leaves a thumb at its end, such as <kbd>Home</kbd> on the start thumb, picks the whole range.

## Props

A Range Slider takes every prop of the [Slider](https://golemui.com/dx/widgets-reference/input-fields/slider.md#props), with the same defaults: `minimum`, `maximum`, `step`, `marks`, `format`, `valuePlacement` and `hint`. It adds the names of its thumbs.

| prop         | type   | description                                                       |
| ------------ | ------ | ----------------------------------------------------------------- |
| `endLabel`   | string | The high thumb's name for screen readers. Defaults to `"Maximum"` |
| `startLabel` | string | The low thumb's name for screen readers. Defaults to `"Minimum"`  |

### Marks and Value Placement

`marks` and `valuePlacement` work as on the [Slider](https://golemui.com/dx/widgets-reference/input-fields/slider.md#marks). With `bubble` or `both`, each thumb shows its own value. At the end of the label, the range reads as `9 – 18`.


```ts title="range-slider.ts"

export default [
  gui.inputs.rangeSlider('hours', {
    maximum: 24,
    marks: [
      {
        value: 0,
        label: '0:00',
      },
      {
        value: 6,
        label: '6:00',
      },
      {
        value: 12,
        label: '12:00',
      },
      {
        value: 18,
        label: '18:00',
      },
      {
        value: 24,
        label: '24:00',
      },
    ],
    valuePlacement: 'both',
    label: 'Opening hours',
    defaultValue: {
      start: 9,
      end: 18,
    },
  }),
];
```

_Live demo on the docs page. Form definition: [range-slider-marks.ts](https://golemui.com/template/widgets-dx/range-slider/range-slider-marks.ts)._

### Thumb Labels

Screen readers name each thumb after the field's label and its own name: "Price per night Minimum" and "Price per night Maximum" by default. Use `startLabel` and `endLabel` to give them names that fit your scale, such as "From" and "To". Both accept a translation config.


```ts title="range-slider.ts"

export default [
  gui.inputs.rangeSlider('price', {
    maximum: 500,
    step: 10,
    format: {
      style: 'currency',
      currency: 'EUR',
      maximumFractionDigits: 0,
    },
    startLabel: 'From',
    endLabel: 'To',
    label: 'Price per night',
    defaultValue: {
      start: 100,
      end: 300,
    },
  }),
];
```

_Live demo on the docs page. Form definition: [range-slider-thumb-labels.ts](https://golemui.com/template/widgets-dx/range-slider/range-slider-thumb-labels.ts)._

## Validation

Range Sliders take a range validator, with `required` and no other rules. `required` fails while there is no range. Word its error with `messages.required`.


```ts title="range-slider.ts"

export default [
  gui.inputs.rangeSlider('ages', {
    minimum: 18,
    maximum: 99,
    hint: 'Move a thumb, or leave the field to see the error.',
    label: 'Age range',
    validator: {
      required: true,
      messages: {
        required: 'Pick an age range',
        invalid: 'Pick an age range',
      },
    },
  }),
];
```

_Live demo on the docs page. Form definition: [range-slider-validation.ts](https://golemui.com/template/widgets-dx/range-slider/range-slider-validation.ts)._

## Styling

Range Sliders take the same CSS Variables as the [Slider](https://golemui.com/dx/widgets-reference/input-fields/slider.md#css-variables), and can be styled as explained in the [Styling Guide](https://golemui.com/dx/styling/overview.md).

### Anatomy

This is the anatomy of the Range Slider widget in case you want to use your CSS styles.


```html title="range-slider-anatomy.html"
<gui-range-slider-input class="gui-range-slider gui-field">
  <gui-range-slider class="gui-field">
    <span class="gui-label" id="fieldUid_label">
      <span class="gui-label__text">Opening hours</span>
      <output class="gui-slider__value" aria-hidden="true">9 – 18</output>
    </span>
    <div class="gui-widget">
      <div class="gui-slider__control gui-slider__control--range">
        <div class="gui-slider__rail" aria-hidden="true">
          <span class="gui-slider__fill" style="--_start: 37.5; --_end: 75"></span>
        </div>
        <div class="gui-slider__ticks" aria-hidden="true">
          <span class="gui-slider__tick" style="--_percent: 0"></span>
          <span class="gui-slider__tick" style="--_percent: 25"></span>
          <span class="gui-slider__tick gui-slider__tick--filled" style="--_percent: 50"></span>
          <span class="gui-slider__tick gui-slider__tick--filled" style="--_percent: 75"></span>
          <span class="gui-slider__tick" style="--_percent: 100"></span>
        </div>
        <input
          type="range"
          class="gui-slider__input"
          id="fieldUid_start"
          min="0"
          max="24"
          step="1"
          aria-labelledby="fieldUid_label fieldUid_start_name"
          aria-valuetext="9"
        />
        <span class="gui-slider__bubble" aria-hidden="true" style="--_percent: 37.5">9</span>
        <span class="gui-visually-hidden" id="fieldUid_start_name">Minimum</span>
        <input
          type="range"
          class="gui-slider__input"
          id="fieldUid_end"
          min="0"
          max="24"
          step="1"
          aria-labelledby="fieldUid_label fieldUid_end_name"
          aria-valuetext="18"
        />
        <span class="gui-slider__bubble" aria-hidden="true" style="--_percent: 75">18</span>
        <span class="gui-visually-hidden" id="fieldUid_end_name">Maximum</span>
      </div>
    </div>
    <div class="gui-slider__footer">
      <div class="gui-slider__tick-labels" aria-hidden="true">
        <span class="gui-slider__tick-label gui-slider__tick-label--first" style="--_percent: 0">
          0:00
        </span>
        <span class="gui-slider__tick-label" style="--_percent: 25">6:00</span>
        <span class="gui-slider__tick-label" style="--_percent: 50">12:00</span>
        <span class="gui-slider__tick-label" style="--_percent: 75">18:00</span>
        <span class="gui-slider__tick-label gui-slider__tick-label--last" style="--_percent: 100">
          24:00
        </span>
      </div>
      <div class="gui-validator gui-validator--empty" id="fieldUid_errors" role="alert"></div>
    </div>
  </gui-range-slider>
</gui-range-slider-input>
```
