hb-range-slider (range-slider)

Category: inputs
Tags: inputs, slider
Package: @htmlbricks/hb-range-slider

Overview

hb-range-slider is a shadow-DOM web component that renders a dual-handle range slider. Two thumbs select a sub-range on a linear domain defined by min and max; the selected interval is mapped to real values and percentages on the track. An optional third handle acts as a single position marker along the same domain; its value appears in the emitted payload as positionValReal and positionPercent.

Optional value bubbles (withbubbles) show rounded min/max values above the outer thumbs. The component uses native <input type="range"> controls (visually hidden) for pointer and keyboard interaction; the visible track, thumbs, and bubbles are styled with Bulma-driven CSS variables.

When the user commits a change (native change on the range inputs), the component dispatches changeRangeValues with the current min, max, and marker positions in both domain units and 0–100 track percent.

Custom element

<hb-range-slider …></hb-range-slider>

Attributes (host)

Web component attributes use snake_case. Values from HTML are strings. Use numeric strings for numbers (for example "0", "42.5"). For booleans where noted, use yes or no (project convention for host markup).

| Attribute | Required | Description | |-----------|----------|-------------| | min | No | Lower bound of the value domain. Default 0 (internal default when missing or invalid). Coerced with Number(). | | max | No | Upper bound of the value domain. Default 100. Must span a range with min for meaningful mapping. Coerced with Number(). | | minval | No | Initial left thumb value in domain units. Clamped to min..max, then converted to an internal left percentage. Consumed once when applied (not kept as a live two-way binding from attributes alone). | | maxval | No | Initial right thumb value in domain units. Clamped to min..max, then converted to an internal right percentage. Consumed once when applied. | | position_value | No | Initial marker thumb value in domain units. Clamped to min..max, then converted to internal marker percentage. Consumed once when applied. 0 is a valid value. | | withbubbles | No | Set to yes to show value bubbles on the min and max thumbs. Omit the attribute for the default (bubbles off). Prefer yes / no for boolean host strings in line with other hb-* inputs. | | id | No | Optional host element id. | | style | No | Optional inline styles on the host element. |

Domain mapping: Internal thumbs move on an abstract 0–100 track. A thumb at percent p maps to real value min + ((max - min) / 100) * p. The marker thumb is kept between the left and right thumbs when percentages are adjusted.

Events

changeRangeValues

Fired on change (after the user finishes adjusting a handle), not on every intermediate input tick.

event.detail (all numbers):

| Property | Description | |----------|-------------| | minValue | Left thumb value in domain units (derived from min, max, and left percent). | | maxValue | Right thumb value in domain units. | | minPercent | Left thumb position on the 0–100 internal track. | | maxPercent | Right thumb position on the 0–100 internal track. | | positionPercent | Marker thumb position on the 0–100 internal track. | | positionValReal | Marker value in domain units. |

TypeScript shapes for Component and Events live in types/webcomponent.type.d.ts.

Example listener:

<hb-range-slider id="range" min="10" max="25" minval="13" maxval="20" withbubbles="yes"></hb-range-slider>
<script>
  document.getElementById("range").addEventListener("changeRangeValues", (e) => {
    console.log(e.detail.minValue, e.detail.maxValue, e.detail.positionValReal);
  });
</script>

Styling

The host forwards Bulma 1.x CSS variables into internal tokens used by the track, thumbs, and bubbles. Prefer --bulma-* on :host or ancestors; see Bulma CSS variables.

| Variable | Role | |----------|------| | --bulma-primary | Selected range fill and bubble background (via --hb-slider-fill / --hb-slider-bubble). | | --bulma-primary-invert | Bubble label text color. | | --bulma-border | Unselected track segments (--hb-slider-track). | | --bulma-scheme-main | Outer thumb face (--hb-slider-thumb-bg). | | --bulma-text | Inner thumb contrast / marker thumb tone (--hb-slider-thumb-inner). | | --hb-slider-background-color | Optional override for fill and bubble tint (defaults through --bulma-primary). |

Internal wiring (from styles/webcomponent.scss): --hb-slider-fill, --hb-slider-track, --hb-slider-thumb-bg, --hb-slider-thumb-inner, --hb-slider-bubble, --hb-slider-bubble-text.

::part names (from extra/docs.ts / styleSetup):

| Part | Description | |------|-------------| | inverse | Host-side wrappers that paint the unfilled track beside the selected range. | | the-range | Filled segment between the two outer thumbs. | | the-thumb | Draggable handles for the range endpoints (and the marker’s outer thumb styling). | | the-thumb-internal | Smaller center handle for the optional marker thumb between the endpoints. | | sign | Value bubble / label attached to a thumb when withbubbles is enabled. |

When bubbles are enabled, the host adds the class hb-range-slider--bubbles on the root container for extra vertical spacing.

Slots

None (htmlSlots is empty in extra/docs.ts).

Examples

Basic range with bubbles:

<hb-range-slider min="0" max="100" minval="20" maxval="80" withbubbles="yes"></hb-range-slider>

Narrow domain with initial marker (matches the withPositionValue example in extra/docs.ts):

<hb-range-slider
  min="10"
  max="25"
  minval="13"
  maxval="20"
  position_value="17"
  withbubbles="yes"
></hb-range-slider>

License

Component metadata in extra/docs.ts lists Apache-2.0 for package licensing information; see the referenced LICENSE.md in that context when distributing the package.