Docs

Main site

Installation Browser support Extend config MCP server
Validation Page speed testing Responsive design
Accordion Aspect Ratio Avatar Badge Banner Bento Grid Blockquote Breadcrumbs Button Callout Card Drawer Dropdown Link Modal Navbar Navblock Pagination Popover Progress Separator Tabs Timeline Toast Tooltip
Checkbox Datepicker File upload Form field Input Label OTP Radio Range Select Textarea Toggle
Header Footer
Accordion Auth Checkbox & Radio Content Drawers Features Modals Statistics & Metrics Teams
Address Contact number Currency symbol Date Emirates ID Name
Close
Home Documentation Components Range

Range

A Range is a slider for choosing a numeric value, or a numeric span between a minimum and a maximum, where the magnitude matters more than the exact figure — residency duration, age filters, fee brackets, search radius. "aegov-range" is built on one or two real native range inputs for full keyboard and form support, with a richer custom track-and-thumb layer drawn on top for consistent, cross-browser styling.

Interactive
Status
Active
Introduced
4.0.x
View source code

Anatomy

aegov-range renders one real native <input type="range"> in single mode, or two (low/high) in range mode — visually hidden but focusable and fully keyboard-driven. A custom track, fill, and one or two thumb elements are drawn on top purely for consistent cross-browser visuals; dragging a custom thumb keeps the underlying native input's value in sync.

Image showing anatomy of a range

Item Name Description
1 Track The full-width background bar representing min to max
2 Fill The coloured segment between the start and the current value (or between the two thumbs in range mode)
3 Thumb The draggable handle — one in single mode, two (low/high) in range mode
4 Value display (optional) Tooltip, in-thumb text, or flanking min/max labels, depending on display
5 Label Text naming the field (label prop)
6 Hint / error message Supporting helper text, which stays visible when the error message appears above it once is-invalid is set

Basics

Set min, max, and value for a single-thumb slider. Add display="tooltip" so the current value floats in a bubble above the thumb — it is positioned over the content above the slider, so it takes no extra layout space.

<aegov-range field-id="range-basics" name="range-basics" label="Search radius (km)" min="1" max="50" value="10" display="tooltip"></aegov-range>

Single vs. dual-thumb mode

Use the default mode="single" for one thumb and one value. Use mode="range" for two thumbs selecting a low/high pair — set value-low and value-high instead of value. The low thumb can never be dragged, clicked, or keyed past the high thumb's value (and vice versa); the component always keeps at least one step of separation between them.

<aegov-range field-id="range-mode-single" name="range-mode-single" label="Monthly income (AED, thousands)" min="0" max="100" value="25" display="tooltip"></aegov-range>
<aegov-range field-id="range-mode-dual" name="range-mode-dual" mode="range" label="Age of dependants" min="0" max="80" value-low="18" value-high="65" display="full"></aegov-range>

Value display

display controls how the current value is shown alongside the slider: none (default, nothing extra), tooltip (a small bubble floating above each thumb, always shown), thumb (the value sits inside an enlarged thumb, always visible), or full (adds fixed min/max labels at each end of the track, on top of the in-thumb value).

<aegov-range field-id="range-display-none" name="range-display-none" label="display = none" value="40"></aegov-range>
<aegov-range field-id="range-display-tooltip" name="range-display-tooltip" label="display = tooltip" value="40" display="tooltip"></aegov-range>
<aegov-range field-id="range-display-thumb" name="range-display-thumb" label="display = thumb" value="40" display="thumb"></aegov-range>
<aegov-range field-id="range-display-full" name="range-display-full" label="display = full" value="40" display="full"></aegov-range>

Min, max, and step

min and max define the bounds; step controls the granularity of both dragging/keying and the minimum enforced gap between thumbs in range mode. Use a fractional step for currency or ratio values, and a larger step (10, 25, 50) when fine precision isn't meaningful.

<aegov-range field-id="range-step-1" name="range-step-1" label="Years of UAE residency" min="0" max="40" step="1" value="5" display="tooltip"></aegov-range>
<aegov-range field-id="range-step-25" name="range-step-25" label="Service fee (AED)" min="0" max="500" step="25" value="200" display="full"></aegov-range>
<aegov-range field-id="range-step-decimal" name="range-step-decimal" label="Acceptance threshold" min="0" max="1" step="0.05" value="0.75" display="thumb"></aegov-range>

Sizes

size accepts five tokens, from xs up to xl. It scales the track thickness only — the 24px thumb stays constant at every size so it remains comfortably tappable on touch devices — and accepts a responsive breakpoint string (e.g. size="sm md:base").

<aegov-range field-id="range-size-xs" name="range-size-xs" label="Extra small" size="xs" value="50"></aegov-range>
<aegov-range field-id="range-size-sm" name="range-size-sm" label="Small" size="sm" value="50"></aegov-range>
<aegov-range field-id="range-size-base" name="range-size-base" label="Base" size="base" value="50"></aegov-range>
<aegov-range field-id="range-size-lg" name="range-size-lg" label="Large" size="lg" value="50"></aegov-range>
<aegov-range field-id="range-size-xl" name="range-size-xl" label="Extra large" size="xl" value="50"></aegov-range>

Variant

variant selects the colour family for the active fill segment, the in-thumb value text, and the thumb's focus ring — the off-track and the thumb body always stay constant (aeblack-100 and white respectively) regardless of variant, so grip contrast stays consistent across every colour family.

Variant Track (constant) Active fill Thumb (constant)
primary aeblack-100 primary-600 white
secondary aeblack-100 secondary-600 white
neutral-max aeblack-100 aeblack-800 white
neutral-min aeblack-100 aeblack-400 white

Variant example

<aegov-range field-id="range-variant-primary" name="range-variant-primary" variant="primary" label="Primary" value="50" display="tooltip"></aegov-range>
<aegov-range field-id="range-variant-secondary" name="range-variant-secondary" variant="secondary" label="Secondary" value="50" display="tooltip"></aegov-range>
<aegov-range field-id="range-variant-neutral-max" name="range-variant-neutral-max" variant="neutral-max" label="Neutral-max" value="50" display="tooltip"></aegov-range>
<aegov-range field-id="range-variant-neutral-min" name="range-variant-neutral-min" variant="neutral-min" label="Neutral-min" value="50" display="tooltip"></aegov-range>

Orientation

Set orientation="vertical" for a vertical slider — well suited to equaliser-style controls or a tall side panel. The track is 200px tall by default; set the --range-height custom property on the host or an ancestor to change it. The minimum sits at the bottom, and Arrow Up raises the value.

<aegov-range field-id="range-vertical-1" name="range-vertical-1" label="Bass" orientation="vertical" value="20" display="tooltip" style="height: 200px"></aegov-range>
<aegov-range field-id="range-vertical-2" name="range-vertical-2" label="Mid" orientation="vertical" value="60" display="tooltip" style="height: 200px"></aegov-range>
<aegov-range field-id="range-vertical-3" name="range-vertical-3" label="Treble" orientation="vertical" value="90" display="tooltip" style="height: 200px"></aegov-range>

Disabled

Set is-disabled="true" to dim the slider, block pointer/touch dragging, and mark the native input(s) disabled — removing them from the tab order and from form submission.

<aegov-range field-id="range-disabled" name="range-disabled" label="Disabled" value="40" is-disabled="true" display="tooltip"></aegov-range>

Validation

is-invalid and error-message apply to every native input the slider renders (both thumbs, in range mode). is-required has no validation effect, because a range always has a value — business rules are the realistic case. A common pattern is a group of business rules checked on aegovValidate — for example, enforcing a minimum span between the two thumbs — using setCustomValidity() to surface a message when the rule fails.

<aegov-range field-id="range-validation" name="range-validation" mode="range" label="Trip duration (days)" min="0" max="30" value-low="14" value-high="16" display="full" is-invalid="true" error-message="Trips must span at least 3 days."></aegov-range>

RTL support

The range is direction-agnostic. When the document or any ancestor is dir="rtl", the fill, the min/max labels, and pointer-to-value mapping all mirror automatically — min sits on the right, max on the left, and dragging toward the start of the track (now the right edge) decreases the value. Arrow keys follow the visual direction as well: Arrow Left increases the value and Arrow Right decreases it. No extra configuration is needed.

<div dir="rtl">
  <aegov-range field-id="range-rtl" name="range-rtl" label="نصف قطر البحث (كم)" min="1" max="50" value="10" display="full"></aegov-range>
</div>

Usage

Here is the recommended usage of a range on any website or application. These are recommended usage guides, however the developer must use the best practices of web and application development to accurately use this component.

Always pair a slider with a visible value, unless the exact number truly doesn't matter
Set display="tooltip", "thumb", or "full" so users get feedback on the number they're choosing, not just its relative position on the track.

Use range mode for a genuine "between X and Y" span, not two independent values
A dual-thumb slider communicates "pick a range" — for two unrelated single numbers (e.g. minimum salary and years of experience), use two separate single-mode sliders or numeric inputs instead.

Do not use a slider when a user needs to enter a precise, arbitrary number
Sliders are great for approximate, bounded magnitudes but a poor way to land on an exact value like a specific salary figure or a date — use a numeric aegov-input (optionally alongside a slider) for that.

Do not seed range mode with value-low and value-high closer together than step
The component will clamp any further interaction to keep the required gap, but a starting pair that already violates it (e.g. value-low="50" value-high="50" step="1") skips that correction until the user actually touches a thumb.

API reference

The following are the properties and references of a range

aegov-range default properties

AttributeDescriptionTypeDefault

field-id

DOM id for the underlying <input type="range"> (single mode) or the low thumb's input ({field-id}-low) plus a high thumb input ({field-id}-high) in range mode. Auto-generated if omitted.

string

auto-generated

name

Reflected on the host for ElementInternals-based form submission. In range mode, submitted as two entries, {name}-low and {name}-high.

string

(none)

mode

Single thumb, or dual thumb for selecting a low/high span.

single | range

single

value

Current value in single mode. Ignored in range mode. Kept within min/max and on a step, like a native range input — on load and whenever value, min, max or step changes.

number

50

value-low

Low thumb value in range mode. Ignored in single mode. Kept within min/max and on a step, like value.

number

25

value-high

High thumb value in range mode. Ignored in single mode. Kept within min/max and on a step, like value.

number

75

min

Minimum value.

number

0

max

Maximum value.

number

100

step

Step increment for both the value grid and the minimum enforced gap between the two thumbs in range mode.

number

1

display

How the current value is shown alongside the slider: none (nothing extra), tooltip (a floating bubble above each thumb, always shown), thumb (value drawn inside an enlarged thumb, always visible), or full (adds fixed min/max labels at each end of the track, on top of the in-thumb value).

none | tooltip | thumb | full

none

orientation

Slider layout direction. In vertical orientation the track is 200px tall by default; set the --range-height custom property on the host or an ancestor to change it. The minimum sits at the bottom.

horizontal | vertical

horizontal

size

Track thickness token. The 24px thumb stays constant at every size. Accepts a responsive breakpoint string, e.g. "sm md:base".

xs | sm | base | lg | xl

base

variant

Colour family for the active fill segment, the in-thumb value text, and the thumb's focus ring (camel for primary, desert for secondary, seablue for the neutrals). The off-track and the thumb body stay constant (aeblack-100 / white) regardless of variant, for a consistent grip across colour families.

primary | secondary | neutral-max | neutral-min

primary

label

Label text. In single mode, renders a real <label for="..."> pointing at the input. In range mode, renders as a plain <span> (a single <label for> can't target two inputs) and is instead woven into each thumb's own aria-label (e.g. "Age of dependants — Range minimum").

string

(none)

is-disabled

Disables the slider — dims it, blocks pointer/touch drag, and sets the native disabled attribute (removing it from the tab order and form submission).

boolean

false

is-required

Sets native required on the single-mode input only. It has no validation effect — a range always has a value — and shows no visual marker. Use setCustomValidity() for business rules.

boolean

false

is-invalid

Visual + aria-invalid invalid state, applied to every native input the component renders.

boolean

false

error-message

Inline error message shown when is-invalid is set. Use the error slot for rich markup instead.

string

''

hint

Helper text shown below the slider. It stays visible while an error shows — the error renders above it and both are announced as the description. Use the hint slot instead for rich markup.

string

''

extra-class

Additional CSS classes applied to the internal wrapper.

string

(none)

This component renders inside a real shadow DOM, so extra-class only applies margin/padding (spacing) utilities — e.g. mt-4, md:px-6. Colour, border, typography, and every other visual utility are silently ignored: this is an isolated component whose internal styles can't be overridden, keeping it visually consistent wherever it's used.

Events

EventDescriptionDetail

aegovRangeInput

Fires continuously while a thumb is being dragged, touched, or moved by a keypress — every intermediate value, not just the final one.

{ value?: number; valueLow?: number; valueHigh?: number }

aegovRangeChange

Fires once the value is committed — on pointer/touch release, or immediately on each keypress (native range inputs fire change per keystroke, unlike text inputs which wait for blur).

{ value?: number; valueLow?: number; valueHigh?: number }

aegovValidate

Unified validation event. See §2.3.

AegovValidationDetail<number | { low: number; high: number }>

Methods

MethodDescription

validate(trigger?)

Imperatively re-runs validation and emits aegovValidate. Returns Promise<{ valid, message, validity }>.

setCustomValidity(message)

Mirrors HTMLInputElement.setCustomValidity(). An empty string clears the custom error.

Slots

SlotDescription

hint

Rich markup for the hint, in place of the plain-text hint prop.

error

Rich markup for the error message, in place of the plain-text error-message prop.

Pass-through attributes

AttributeNotes

aria-*

Forwarded automatically, except aria-invalid (owned internally). Your aria-describedby is kept and combined with the hint/error ids. In range mode, forwarded only onto the single-thumb input path — the two dual-thumb inputs use the component's own derived ids and composed aria-labels instead.

data-*

Forwarded automatically.

form, tabindex, title, autofocus

Forwarded onto the (single-mode) native input.

id

Not forwarded. Use field-id to control the slider's real inner id(s).

class, style

Applied to the host element — stays host-only, never forwarded inward. In vertical orientation, change the track length with the --range-height custom property (default 200px).

Notes

The following notes are applicable of this component.

Built-in accessibility

  • aegov-range is built on one or two real <input type="range"> elements, so screen readers, the OS accessibility rotor, and keyboard handling all treat it as a native slider — nothing is reimplemented in ARIA-only markup.
  • aria-valuemin, aria-valuemax, and aria-valuenow are kept in sync as the user drags or types. In range mode, the low thumb's aria-valuemax is clamped to the current high value (and the high thumb's aria-valuemin to the current low value), so each handle always reports its own currently-permitted range.
  • The custom thumb-and-track visuals sit on top of the real native input(s) purely for consistent cross-browser styling — the native input drives all keyboard interaction, and pointer/touch dragging on the custom thumb keeps the native input's value in sync via re-render, so both interaction paths end up in the same state.
  • Each thumb in range mode gets a bilingual, self-composed aria-label combining the field's label with the thumb's role — e.g. "Age of dependants — Range minimum" in English, or the Arabic equivalent when the component resolves the document as RTL. No developer translation work is needed.
  • Hint and error text are wired to every native input the component renders via aria-describedby automatically. The hint stays visible while an error shows, so the description reads the error, then the hint. The error region only takes role="alert" after the user has blurred at least once, so a validation message present at initial load isn't announced as an interruption.

Developer responsibility

The following is required for a developer to add additionally or pay attention to regarding this component.

  • Always provide a label that names the unit being chosen (km, AED, years) — a bare slider gives users no way to interpret the number.
  • Pair a slider with a visible numeric readout whenever precision matters — set display to tooltip, thumb, or full rather than leaving it at none.
  • Keep the value range realistic for a slider. When a user needs to type an exact, arbitrary number, pair with (or use instead) a numeric aegov-input.
  • In range mode, seed value-low/value-high so that value-low + step ≤ value-high — the component clamps this on every interaction, but a seeded starting value that already violates it is not corrected automatically.
  • In vertical orientation, the track is 200px tall by default — set --range-height on the host or an ancestor when you need a different length.

Additional notes

  • size accepts a responsive breakpoint string, the same convention used by Badge, Banner, and Checkbox (e.g. size="sm md:base").
  • The off-track and the thumb body never change colour with variant — only the active fill segment, the in-thumb value text and the focus ring do. This is a deliberate constant, not a limitation, so the grip stays equally visible across every colour family.
  • name/form submission is handled via ElementInternals on the host element. In range mode this submits two separate FormData entries, {name}-low and {name}-high, rather than one combined value.

Keyboard support

Key Function
Tab Moves focus to the slider (or, in range mode, to the low thumb, then the high thumb as a separate stop).
Shift + Tab Moves focus to the previous focusable element.
Arrow Right / Arrow Up Increases the focused thumb's value by one step. In RTL, Left and Right follow the visual direction, so Arrow Left increases and Arrow Right decreases.
Arrow Left / Arrow Down Decreases the focused thumb's value by one step (reversed for Left and Right in RTL, as above).
Home Jumps the focused thumb to its minimum (min for a single thumb or the low thumb; the low thumb's current value, plus one step, for the high thumb).
End Jumps the focused thumb to its maximum (max for a single thumb or the high thumb; the high thumb's current value, minus one step, for the low thumb).
Page Up / Page Down Moves the value by a larger, browser-defined increment.

In range mode, the low and high thumbs are always reachable and adjustable independently via keyboard, exactly as with mouse or touch — a fully-clamped, native-slider-driven interaction where each thumb is its own tab stop.