Slider

Slider widgets are Input Fields that pick a number on a scale. The user drags the thumb, presses the track, or moves it with the arrow keys, Page Up, Page Down, Home and End. The value shows at the end of the label.

import { gui } from '@golemui/gui-shared';

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

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "slider",
      "path": "volume",
      "label": "Volume",
      "defaultValue": 40
    }
  ]
}

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 ”–”. Home, 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.

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

Use the property hint to add a description.

import { gui } from '@golemui/gui-shared';

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

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "slider",
      "path": "volume",
      "label": "Volume",
      "props": {
        "hint": "Applies to every speaker in the room."
      },
      "defaultValue": 40
    }
  ]
}

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.

import { gui } from '@golemui/gui-shared';

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,
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "slider",
      "path": "guests",
      "label": "Guests",
      "props": {
        "minimum": 1,
        "maximum": 8
      },
      "defaultValue": 2
    },
    {
      "kind": "input",
      "type": "slider",
      "path": "temperature",
      "label": "Temperature",
      "props": {
        "minimum": 16,
        "maximum": 28,
        "step": 0.5
      },
      "defaultValue": 21
    }
  ]
}

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.

import { gui } from '@golemui/gui-shared';

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,
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "slider",
      "path": "brightness",
      "label": "Brightness",
      "props": {
        "step": 10,
        "marks": true
      },
      "defaultValue": 40
    },
    {
      "kind": "input",
      "type": "slider",
      "path": "rating",
      "label": "Rating",
      "props": {
        "minimum": 1,
        "maximum": 5,
        "marks": [
          {
            "value": 1,
            "label": "Poor"
          },
          3,
          {
            "value": 5,
            "label": "Great"
          }
        ]
      },
      "defaultValue": 4
    }
  ]
}

Format

Use the property format to set how the value reads, with the options of Intl.NumberFormat: 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.

import { gui } from '@golemui/gui-shared';

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,
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "slider",
      "path": "opacity",
      "label": "Opacity",
      "props": {
        "maximum": 1,
        "step": 0.05,
        "format": {
          "style": "percent"
        }
      },
      "defaultValue": 0.6
    },
    {
      "kind": "input",
      "type": "slider",
      "path": "budget",
      "label": "Budget",
      "props": {
        "maximum": 5000,
        "step": 100,
        "format": {
          "style": "currency",
          "currency": "EUR",
          "maximumFractionDigits": 0
        }
      },
      "defaultValue": 1500
    }
  ]
}

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. Escape hides the bubble.

import { gui } from '@golemui/gui-shared';

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,
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "slider",
      "path": "bass",
      "label": "Bass",
      "props": {
        "minimum": -10,
        "maximum": 10,
        "valuePlacement": "bubble"
      },
      "defaultValue": 0
    },
    {
      "kind": "input",
      "type": "slider",
      "path": "treble",
      "label": "Treble",
      "props": {
        "minimum": -10,
        "maximum": 10,
        "valuePlacement": "both"
      },
      "defaultValue": 3
    }
  ]
}

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.

import { gui } from '@golemui/gui-shared';

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',
      },
    },
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "slider",
      "path": "volume",
      "label": "Volume",
      "props": {
        "hint": "Move the thumb, or leave the field to see the error."
      },
      "validator": {
        "type": "number",
        "required": true,
        "messages": {
          "invalid": "Pick a volume"
        }
      }
    }
  ]
}

See Validators for every rule of the number validator.

Styling

Sliders can be styled as explained in the Styling Guide.

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.

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