GUILD OF GLEKS UIv21.19.0

gog-slider

Slider

A native <input type="range"> under a drawn track: one value or a two-thumb range, horizontal or vertical, with a label, a steady readout and full ControlValueAccessor support.

Overview

Import the component and drop it into a template.

typescript
import { SliderComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [SliderComponent],
})

Basic usage — a labeled slider bound with [(value)]:

40
0100
value: 40 · 0 valueChange
<div>
  <gog-slider
    label="Volume"
    [step]="5"
    [(value)]="volume"
    (valueChange)="changes.update((n) => n + 1)"
  />
  <!-- valueChange fires on every step of a drag, not once at the end. -->
  <code>value: {{ volume() }} · {{ changes() }} valueChange</code>
</div>

Examples

States

Five states, each in both modes. A slider has no size input: its track, thumb and type come from the --gog-slider-* tokens alone. [showThumb]="false" draws a meter-like bar that still answers the pointer and the keyboard — there is just nothing drawn to grab. Disabled dims the whole control once, label and error included.

40
0100
20 – 70
0100
40
0100
20 – 70
0100
0100
0100
40
0100
20 – 70
0100
40
0100
Too loud
20 – 70
0100
Too wide
<gog-slider label="Default" [value]="40" />
<gog-slider label="Default · range" range [rangeValue]="{ start: 20, end: 70 }" />
<!-- A meter-like bar that still answers the pointer and the keyboard. -->
<gog-slider label="showThumb false" [showThumb]="false" [value]="40" />
<gog-slider
  label="showThumb false · range"
  range
  [showThumb]="false"
  [rangeValue]="{ start: 20, end: 70 }"
/>
<gog-slider label="showValue false" [showValue]="false" [value]="40" />
<gog-slider
  label="showValue false · range"
  range
  [showValue]="false"
  [rangeValue]="{ start: 20, end: 70 }"
/>
<gog-slider label="Disabled" disabled [value]="40" />
<gog-slider label="Disabled · range" range disabled [rangeValue]="{ start: 20, end: 70 }" />
<gog-slider label="Error" errorMessage="Too loud" [value]="40" />
<gog-slider
  label="Error · range"
  range
  errorMessage="Too wide"
  [rangeValue]="{ start: 20, end: 70 }"
/>

min, max and step

step works at any scale. The readout reserves the width of the longest number min, max and step can print and uses tabular figures, so it never shifts as the value changes. It is a plain number — there is no formatter, so a unit or a currency belongs in the label.

40
0100
0.35
01
-15
-4040
2750
010000
<!-- The readout reserves the widest number these can print, so it never shifts. -->
<gog-slider label="0 to 100, step 1" [value]="40" />
<gog-slider label="0 to 1, step 0.05" [min]="0" [max]="1" [step]="0.05" [value]="0.35" />
<gog-slider label="-40 to 40, step 5" [min]="-40" [max]="40" [step]="5" [value]="-15" />
<gog-slider
  label="Budget, € (0 to 10 000, step 250)"
  [min]="0"
  [max]="10000"
  [step]="250"
  [value]="2750"
/>

Vertical

The same native input turned with writing-mode, not a custom drag, so dragging, touch and every arrow key keep working; the value grows upward, like a fader. Its length is --gog-slider-vertical-length (160px), and fullWidth does nothing here — a vertical slider's width is its thickness.

60
0100
30 – 70
0100
80
0100
<gog-slider label="Gain" orientation="vertical" [(value)]="gain" />
<gog-slider label="Band" orientation="vertical" range [(rangeValue)]="band" />
<gog-slider label="Level" orientation="vertical" [showThumb]="false" [value]="80" />

Width

Full width by default — the opposite of the other controls, because a track has no content to size to. [fullWidth]="false" takes --gog-slider-auto-width (240px) instead of shrinking.

40
0100
40
0100
<gog-slider label="fullWidth (default)" [value]="40" />
<!-- Not shrink-wrapped: a track has no content, so it takes --gog-slider-auto-width. -->
<gog-slider label='[fullWidth]="false"' [fullWidth]="false" [value]="40" />

No visible label

ariaLabel names a slider that has no label. On a range slider it names both thumbs, followed by "Minimum" and "Maximum" 21.15.0 — before, those thumbs were a bare "Minimum" and "Maximum".

60
0100
20 – 70
0100
<gog-slider ariaLabel="Opacity" [value]="60" />
<!-- Each thumb is named from ariaLabel: "Price Minimum", "Price Maximum". -->
<gog-slider ariaLabel="Price" range [rangeValue]="{ start: 20, end: 70 }" />

Range — two thumbs

range puts a second thumb on the track and switches the model: bind [(rangeValue)], a GogSliderRange{ start, end }, instead of [(value)]. Each thumb is its own native input and its own Tab stop, and neither can pass the other — a drag that tries stops where the other thumb is. Only the thumbs take the pointer in this mode: a press on the bare track does nothing, the price of two inputs sharing one track.

40 – 120
0200
rangeValue: 40–120 · 0 rangeValueChange
<div>
  <gog-slider
    label="Price"
    range
    [min]="0"
    [max]="200"
    [step]="5"
    startAriaLabel="Lowest price"
    endAriaLabel="Highest price"
    [(rangeValue)]="price"
    (rangeValueChange)="changes.update((n) => n + 1)"
  />
  <code>rangeValue: {{ price().start }}–{{ price().end }} · {{ changes() }} rangeValueChange</code>
</div>

Units in the value — valueFormat21.19.0

One function, (value: number) => string, writes the readout, the min and max labels and each thumb's aria-valuetext. The price range reads "€40 – €120" on screen and "€40" to a screen reader, where without it the reader hears "40" and the unit lives only in the label. The readout's width is reserved from the formatted endpoints, so a longer string still does not shift the track while you drag.

€40 – €120
€0€200
1 h 30 min
15 min4 h
<gog-slider
  label="Price"
  range
  [min]="0"
  [max]="200"
  [step]="5"
  [valueFormat]="euros"
  [(rangeValue)]="price"
/>
<gog-slider
  label="Duration"
  [min]="15"
  [max]="240"
  [step]="15"
  [valueFormat]="duration"
  [(value)]="minutes"
/>

Thumbs that meet

Both thumbs start at 200, on top of each other at the end of the track. Drag left: the start thumb comes away 21.15.0. Before, the end thumb was always the one under the pointer — it can go neither past max nor below the start thumb, so a mouse or a finger had no way out; only the keyboard did. The form control here carries the { start, end } pair: in range mode, that is what it holds.

200 – 200
0200
value: 200–200
<div>
  <!-- In range mode the form control carries the { start, end } pair. -->
  <gog-slider label="Price" range [min]="0" [max]="200" [formControl]="control" />
  <code>value: {{ control.value.start }}–{{ control.value.end }}</code>
</div>

Pinning one end

startDisabled / endDisabled pin one end and leave the other movable. They add to disabled rather than replace it, and unlike it they dim only the pinned thumb — the track stays live for the other.

20 – 60
0100
20 – 60
0100
<gog-slider label="Floor pinned" range startDisabled [(rangeValue)]="floorPinned" />
<gog-slider label="Ceiling pinned" range endDisabled [(rangeValue)]="ceilingPinned" />

A value outside min and max

The control draws a value clamped to [min, max] but does not write the clamp back: bound to 150 with max at 100, it shows 100 and the model still reads 150 until someone moves the thumb. Clamp at the source if the model has to agree. A form control's writeValue is different — it does clamp.

100
0100
value: 150
<div>
  <!-- Drawn clamped to [min, max]; the model keeps 150 until the thumb moves. -->
  <gog-slider label="Clamped" [(value)]="level" />
  <div>
    <gog-button variant="outline" size="sm" (gogClick)="level.set(150)">value.set(150)</gog-button>
  </div>
  <code>value: {{ level() }}</code>
</div>

Reactive forms

Validators.min(20) on a control that starts at 10. With errorDisplay="auto" the error waits until the slider is touched — focus it and Tab away, or use the button — and moving the thumb past 20 clears it.

10
0100
value: 10 · valid: false · touched: false · disabled: false
<div>
  <gog-slider
    label="Budget"
    [formControl]="control"
    errorDisplay="auto"
    errorMessage="At least 20"
  />
  <div>
    <gog-button variant="outline" size="sm" (gogClick)="control.markAsTouched()">
      markAsTouched()
    </gog-button>
    <gog-button variant="outline" size="sm" (gogClick)="toggleDisabled()">
      {{ control.disabled ? 'enable()' : 'disable()' }}
    </gog-button>
  </div>
  <code>
    value: {{ control.value }} · valid: {{ control.valid }} · touched: {{ control.touched }} ·
    disabled: {{ control.disabled }}
  </code>
</div>

App-wide defaults — GOG_CONFIG

control.errorDisplay is the only key a slider reads. Both sliders start at 10 under Validators.min(20): the first takes 'auto' from the config and holds the message back until it is touched; the second sets 'manual' itself and shows it at once. orientation has no config key — it is a layout decision, not a house style. See Global Configuration.

10
0100
10
0100
At least 20
<!-- errorDisplay unset: 'auto' from the config holds the error until the slider is touched. -->
<gog-slider
  label="errorDisplay from the config"
  [formControl]="fromConfig"
  errorMessage="At least 20"
/>
<gog-slider
  label='errorDisplay="manual" — the instance wins'
  errorDisplay="manual"
  [formControl]="manual"
  errorMessage="At least 20"
/>

Accessibility

A native <input type="range"> under a drawn track: the slider role, the value and the keys all come from the platform, and the drawing is out of the accessibility tree.

  • Keyboard — the arrow keys move one step, Home/End jump to min/max, and Page Up/Page Down take larger steps. Vertical answers Up/Down as well as Left/Right. In range mode each thumb is its own tab stop.
  • Name — a visible label names the input through for; without one, ariaLabel. With neither the input is still named "Slider", which says nothing — do not ship that. One <label> cannot name two inputs, so each range thumb carries its own aria-label: the label (or ariaLabel) followed by "Minimum"/"Maximum", or by startAriaLabel/endAriaLabel.
  • Value — explicit aria-valuemin/max/now follow the value as it moves. On a range thumb the bounds narrow to the other thumb, since that is as far as it can go. With valueFormat21.19.0 each thumb also carries an aria-valuetext in the same words as the readout, so "€40" is heard rather than "40".
  • Error — aria-invalid and an aria-describedby pointing at the message.
  • Pointer targets — in single mode the whole track is the target. In range mode only the thumbs are, and each takes the pointer across 24x24 (--gog-slider-range-target-size, WCAG 2.5.8) centred on the drawn thumb, horizontal or vertical 21.15.1. The keyboard reaches both thumbs fully either way.

API Reference

Inputs

NameTypeDefaultDescription
valuenumber (model)0Two-way bindable value via [(value)]. Also driven by Angular Forms through writeValue/registerOnChange when used with formControlName/[formControl]/ngModel. This model is ignored while range is true; a form control is not, and carries the { start, end } pair instead.
rangebooleanfalseSwitches to two-thumb mode for picking a range instead of a single value. Bind [(rangeValue)] instead of [(value)] — the two models are mutually exclusive. A form control carries whichever the mode is: a number, or a { start, end } pair.
rangeValueGogSliderRange (model){ start: 0, end: 100 }Two-way bindable { start, end } pair. Used only when range is true.
startDisabledbooleanfalseDisables only the lower thumb in range mode — pinning a floor while the ceiling stays movable. ORed with disabled, never overriding it, and it does not dim the whole control the way disabled does.
endDisabledbooleanfalseDisables only the upper thumb in range mode. Mirrors startDisabled.
startAriaLabelstring'Minimum'Accessible name for the lower thumb, prefixed with label when one is set ('Price Minimum'), or with ariaLabel when there is no label (since 21.15.0). A shared <label> cannot be associated with two inputs via for, so each thumb needs its own name.
endAriaLabelstring'Maximum'Accessible name for the upper thumb, prefixed the same way as startAriaLabel.
labelstring''Field label.
minnumber0Minimum value.
maxnumber100Maximum value.
stepnumber1Increment step, e.g. 0.01 for fine-grained values.
showValuebooleantrueShows the current numeric value next to the label.
showThumbbooleantrueSet false to render a bare filled track — a range indicator with no drag handle.
errorMessagestring''Error text to display. Visibility is governed by errorDisplay.
errorDisplay'auto' | 'manual'GOG_CONFIG.control.errorDisplay ?? 'manual''manual': shown for as long as errorMessage is non-empty — you decide the timing. 'auto': shown once the attached FormControl is touched and invalid; falls back to manual without one.
ariaLabelstring''Accessible name for the field when there is no visible label.
valueFormat21.19.0((value: number) => string) | nullnullWrites the readout, the min and max labels and each thumb's aria-valuetext — so a unit reaches a screen reader as well as the screen. Unset, the number is printed as is and no aria-valuetext is added.
disabledbooleanfalseDisables dragging and keyboard input.
fullWidthbooleantrueFills its container by default. A track has no content of its own to shrink-wrap to, so [fullWidth]="false" instead sizes it to --gog-slider-auto-width (240px by default) — a fixed, themeable fallback rather than a content-derived one. Ignored when vertical, since a vertical slider’s width is its thickness, not its length.
orientation'horizontal' | 'vertical''horizontal'Which way the track runs. Picked per instance — it is a layout decision rather than a house style, so there is no global default for it. A vertical slider takes its length from --gog-slider-vertical-length (160px).

Outputs

NamePayloadDescription
valueChangenumberEmitted on every step of a drag or key press, not once at the end. Comes from the value model input.
rangeValueChangeGogSliderRangeThe same, for the { start, end } pair in range mode.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.control.errorDisplay

Styling Tokens

Every CSS custom property the slider paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-slider-label-color / -label-font-family / -label-font-size / -label-font-weight / -label-letter-spacing / -label-line-height / -label-text-transformField label. Each aliases its --gog-field-label-* counterpart.
--gog-slider-value-colorThe current value readout.
--gog-slider-track-bg / -fill-bgTrack, empty and filled. The fill is applied as background rather than background-color, so -fill-bg also accepts a gradient.
--gog-slider-track-border-width / -track-border-style / -track-border-colorAn optional border on the track — transparent by default, the same opt-in convention as --gog-button-primary-border.
--gog-slider-thumb-bg / -thumb-border / -thumb-glow-color / -thumb-glow-sizeDrag handle, and the glow around it. -thumb-glow-color was --gog-slider-thumb-shadow until 21.13.0 — it always held a colour, not a shadow — and the old name stopped resolving in 21.14.0.
--gog-slider-range-target-sizeA range thumb’s pointer target, 24px (WCAG 2.5.8). The drawn thumb stays --gog-slider-thumb-size; this is the invisible area around it that takes the press. New in 21.15.0.
--gog-slider-auto-width / -vertical-lengthSize of a slider that does not fill its container: width when horizontal, length when vertical.
--gog-slider-focus-ringKeyboard focus ring.