# Slider

> A Slider widget to pick a number on a scale by dragging a thumb, with steps, tick marks and a formatted value

Slider widgets are [Input Fields](https://golemui.com/dx/widgets-reference/input-fields/overview.md) that pick a number on a scale. The user drags the thumb, presses the track, or moves it with the arrow keys, <kbd>Page Up</kbd>, <kbd>Page Down</kbd>, <kbd>Home</kbd> and <kbd>End</kbd>. The value shows at the end of the label.


```ts title="slider.ts"

export default [
  gui.inputs.slider('volume', {
    label: 'Volume',
    defaultValue: 40,
  }),
];
```

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

The value is a number. Without a `defaultValue`, the slider has no value until the user moves the thumb: the thumb rests at `minimum` and the value reads "–". <kbd>Home</kbd>, a key toward the minimum or a press on the thumb picks `minimum`. To pick a low and a high value, use the [Range Slider](https://golemui.com/dx/widgets-reference/input-fields/range-slider.md).

## Props

Use these `props` to customize your Slider widget.

| prop             | type                                        | description                                                                                              |
| ---------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `format`         | object                                      | How the value reads: `Intl.NumberFormat` options, such as `{ "style": "percent" }`                       |
| `hint`           | string                                      | A description to display below the label                                                                 |
| `marks`          | boolean \| array                            | `true` draws a tick at every step. A list draws ticks at its values, each a number or `{ value, label }` |
| `maximum`        | number                                      | The highest value. Defaults to `100`                                                                     |
| `minimum`        | number                                      | The lowest value. Defaults to `0`                                                                        |
| `step`           | number                                      | The distance between two values, from `minimum`. Defaults to `1`                                         |
| `valuePlacement` | `'label' \| 'bubble' \| 'both' \| 'hidden'` | Where the value shows. Defaults to `'label'`                                                             |

### Hint

<Aside>A `label` is required for the `hint` to be displayed.</Aside>

Use the property `hint` to add a description.


```ts title="slider.ts"

export default [
  gui.inputs.slider('volume', {
    hint: 'Applies to every speaker in the room.',
    label: 'Volume',
    defaultValue: 40,
  }),
];
```

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

### Min, Max & Step

Use `minimum` and `maximum` to set the ends of the scale, and `step` to set the distance between two values. Steps can be decimals.


```ts title="slider.ts"

export default [
  gui.inputs.slider('guests', {
    minimum: 1,
    maximum: 8,
    label: 'Guests',
    defaultValue: 2,
  }),
  gui.inputs.slider('temperature', {
    minimum: 16,
    maximum: 28,
    step: 0.5,
    label: 'Temperature',
    defaultValue: 21,
  }),
];
```

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

### Marks

Use the property `marks` to draw ticks on the track. `true` draws one at every step, up to 101 of them. A list draws ticks only at its values: each item is a number, or an object with a `value` and a `label` that shows under the track.


```ts title="slider.ts"

export default [
  gui.inputs.slider('brightness', {
    step: 10,
    marks: true,
    label: 'Brightness',
    defaultValue: 40,
  }),
  gui.inputs.slider('rating', {
    minimum: 1,
    maximum: 5,
    marks: [
      {
        value: 1,
        label: 'Poor',
      },
      3,
      {
        value: 5,
        label: 'Great',
      },
    ],
    label: 'Rating',
    defaultValue: 4,
  }),
];
```

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

### Format

Use the property `format` to set how the value reads, with the options of [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options): `style`, `currency`, `currencyDisplay`, `unit`, `unitDisplay`, `minimumFractionDigits`, `maximumFractionDigits` and `useGrouping`. The format applies to the value next to the label, to the bubble and to what screen readers read. The value in the form data stays a plain number, such as `0.6` or `1500`.


```ts title="slider.ts"

export default [
  gui.inputs.slider('opacity', {
    maximum: 1,
    step: 0.05,
    format: {
      style: 'percent',
    },
    label: 'Opacity',
    defaultValue: 0.6,
  }),
  gui.inputs.slider('budget', {
    maximum: 5000,
    step: 100,
    format: {
      style: 'currency',
      currency: 'EUR',
      maximumFractionDigits: 0,
    },
    label: 'Budget',
    defaultValue: 1500,
  }),
];
```

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

### Value Placement

Use the property `valuePlacement` to set where the value shows: `label`, the default, at the end of the label; `bubble`, over the thumb while it is hovered, focused or dragged; `both`; or `hidden`. Screen readers read the value from the thumb in every case. <kbd>Escape</kbd> hides the bubble.


```ts title="slider.ts"

export default [
  gui.inputs.slider('bass', {
    minimum: -10,
    maximum: 10,
    valuePlacement: 'bubble',
    label: 'Bass',
    defaultValue: 0,
  }),
  gui.inputs.slider('treble', {
    minimum: -10,
    maximum: 10,
    valuePlacement: 'both',
    label: 'Treble',
    defaultValue: 3,
  }),
];
```

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

## Validation

Sliders take a number validator. Since a slider has no value until the user moves it, `required` works: the missing value fails the number type check, so word that error with `messages.invalid`.


```ts title="slider.ts"

export default [
  gui.inputs.slider('volume', {
    hint: 'Move the thumb, or leave the field to see the error.',
    label: 'Volume',
    validator: {
      required: true,
      messages: {
        invalid: 'Pick a volume',
      },
    },
  }),
];
```

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

See [Validators](https://golemui.com/dx/features/validators.md) for every rule of the number validator.

## Styling

Sliders can be styled as explained in the [Styling Guide](https://golemui.com/dx/styling/overview.md).

### CSS Variables

Following you will find a list with the CSS Variables and a quick description of what you will style.

| CSS Variable              | Description                                                          |
| ------------------------- | -------------------------------------------------------------------- |
| `--gui-slider-thumb-size` | Size of the thumb. Defaults to `1.25rem`                             |
| `--gui-slider-track-size` | Thickness of the track. Defaults to `0.25rem`                        |
| `--gui-intent-primary`    | The filled part of the track, the ticks in it and the thumb's border |
| `--gui-border-strong`     | The rest of the track and its ticks                                  |
| `--gui-tooltip-bg`        | Background of the bubble. Defaults to `--gui-bg-inverse`             |
| `--gui-tooltip-text`      | Text of the bubble. Defaults to `--gui-text-inverse`                 |
| `--gui-intent-error`      | Border of the thumb when invalid                                     |

### Anatomy

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


```html title="slider-anatomy.html"
<gui-slider-input class="gui-slider gui-field">
  <gui-slider class="gui-field">
    <label class="gui-label" for="fieldUid" id="fieldUid_label">
      <span class="gui-label__text">Rating</span>
      <output class="gui-slider__value" aria-hidden="true">4</output>
    </label>
    <div class="gui-widget">
      <div class="gui-slider__control">
        <div class="gui-slider__rail" aria-hidden="true">
          <span class="gui-slider__fill" style="--_start: 0; --_end: 75"></span>
        </div>
        <div class="gui-slider__ticks" aria-hidden="true">
          <span class="gui-slider__tick gui-slider__tick--filled" style="--_percent: 0"></span>
          <span class="gui-slider__tick gui-slider__tick--filled" style="--_percent: 50"></span>
          <span class="gui-slider__tick" style="--_percent: 100"></span>
        </div>
        <input
          type="range"
          class="gui-slider__input"
          id="fieldUid"
          min="1"
          max="5"
          step="1"
          aria-valuetext="4"
        />
      </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">
          Poor
        </span>
        <span class="gui-slider__tick-label gui-slider__tick-label--last" style="--_percent: 100">
          Great
        </span>
      </div>
      <div class="gui-validator gui-validator--empty" id="fieldUid_errors" role="alert"></div>
    </div>
  </gui-slider>
</gui-slider-input>
```
