Control scrubber

The control scrubber is a member of the control family. In a regular slider, the handle moves along a fixed track. In a scrubber, it is the other way around: a window stays in the middle, and the strip behind it moves. Drag the strip to change the value, or tap a point on the strip to bring it under the window.

The strip can be wider than the control, so only a part of the range is visible at a time. That makes each pixel of dragging change the value less, which helps with precise picks in a small space. The strip can also repeat, for ranges that go round, like hue.

The Light color feature of the tile card uses it to pick the hue of a light.

It is not yet part of the live components on this site, so there is no demo here.

Use a control scrubber for:

• A value in a range that goes round, like hue, where the end meets the start
• A value with a wide range in a small space, where a regular control slider would be too coarse

Don't use a control scrubber for:

• An amount, like brightness or volume. Use a control slider, where the fill shows how much.
• Forms and settings. Use a regular slider.

1. Rail: the background of the control, a light tint
2. Strip: the background that moves, like a gradient of all hues
3. Window: the frame in the middle that points at the current value. It is optional.

With wrapping on, the strip repeats, and the value wraps around at the ends. Dragging past 360 degrees of hue lands on 0 again. Without wrapping, the value stops at the minimum and the maximum.

Show the window when there is a current value to point at. Leave it off when there is none, like the color of a light that is off, or that has no color yet.

By default, the strip is as wide as the control. Make it wider to show only a part of the range at a time. The light color feature makes the hue strip at least three times as wide as the control is high.

• Dragging: dragging the strip changes the value. Dragging it to the left moves the strip along, so a higher value comes under the window. A drag starts after 10px of horizontal movement, so a vertical scroll of the page still works.
• Tapping: tapping a point on the strip brings that point under the window.
• Stepping: while someone drags, the value follows the finger. When they let go, it snaps to the nearest step.
• Cancel: when the system cancels a drag, the value goes back to what it was.
• Motion: the strip moves to a new value in 180ms, ease-in-out. While someone drags, it follows without delay.
• Disabled: dragging, tapping, and the keyboard do nothing. The cursor shows that it is not allowed.

• Give it a label, and a unit when there is one, like degrees for hue. The value has no visible text, so the label and the unit are what screen readers announce.
• Hide the window when there is no current value, rather than pointing at a value that isn't there.

The value is sent when the key is released. The arrow keys do not swap in a right to left language.

Keyboard focus shows a 2px ring around the control, in its color. The scrubber stays focusable when disabled.

The whole control is the target, 40px high by default.

The scrubber is announced as a slider, with its label and its value, formatted with the unit, like "200°".

The scrubber has the role slider, with aria-label from label, aria-valuenow, aria-valuemin, aria-valuemax, aria-valuetext with the formatted value and unit, aria-orientation="horizontal", and aria-disabled.

• Controls: the rest of the control family, like the control slider
• Color picker: a color wheel for hue and saturation together
• Tile card: where the scrubber shows up, in the light color feature

The element is <ha-control-scrubber>. Set the background of the strip with a CSS custom property:

<ha-control-scrubber
  wrap
  show-handle
  min="0"
  max="360"
  unit="°"
  label="Hue"
  style="--control-scrubber-track-width: 200%"
></ha-control-scrubber>

ha-control-scrubber {
  --control-scrubber-background: linear-gradient(
    to right,
    hsl(0 100% 50%),
    hsl(120 100% 50%),
    hsl(240 100% 50%),
    hsl(360 100% 50%)
  );
}

• value: the current value.
• min and max: the range. Default to 0 and 100.
• step: the step size. Defaults to 1.
• wrap: repeats the strip, and wraps the value around at the ends.
• show-handle: shows the window.
• round-value: rounds the value that screen readers announce.
• label: the accessible name.
• unit: the unit, used in the value that screen readers announce.
• disabled: ignores dragging, tapping, and the keyboard.
• touch-action: the touch action of the strip. Defaults to pan-y, so the page still scrolls vertically.

• locale: the locale used to format the value.

• value-changed: the value was picked, after a drag, a tap, or when a key is released.
• slider-moved: the value while someone drags or holds a key. When they let go, it fires with no value.

• --control-scrubber-color: the focus ring. Defaults to var(--primary-color).
• --control-scrubber-background: the strip. Defaults to var(--disabled-color).
• --control-scrubber-rail-color and --control-scrubber-rail-opacity: the rail. Default to var(--disabled-color) and 0.2.
• --control-scrubber-thickness: the height. Defaults to 40px.
• --control-scrubber-border-radius: the corners. Defaults to var(--ha-border-radius-md).
• --control-scrubber-track-width: the width of the strip. Defaults to 100%, and can't be less.
• --control-scrubber-inset-shadow: an inner shadow. Defaults to none.

Source: src/components/ha-control-scrubber.ts