Range Field

Two native thumbs on one track, kept in order. Custom element

Choosing between components

Use Range Field when the value is a span. For a single value, Range is CSS over one native input and needs no JavaScript at all.

Markup you author

Both thumbs are native range inputs with their own name, so the pair submits as two entries and resets natively with scripting off. Give each one its own accessible name saying which end it is; nothing else can tell them apart in a screen reader.

Range Field

Copy this markup

<div class="ui-field">
  <span class="ui-label" id="budget-label">Monthly budget</span>
  <ui-range-field id="budget" aria-labelledby="budget-label">
    <span data-ui-part="track">
      <input data-ui-part="from" type="range" name="budget-from" value="120" min="0" max="500" step="10" aria-label="Monthly budget, lower bound" aria-describedby="budget-description">
      <input data-ui-part="to" type="range" name="budget-to" value="380" min="0" max="500" step="10" aria-label="Monthly budget, upper bound" aria-describedby="budget-description">
    </span>
    <output data-ui-part="output">120 – 380</output>
  </ui-range-field>
  <p class="ui-description" id="budget-description">A thumb stops at its neighbour rather than swapping with it.</p>
</div>

Install

Styles and registration

import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/core/range-field.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
import '@timelessui/components/css/themes/atmosphere/range-field.css'
import '@timelessui/components/register/ui-range-field'

A register/ import is a side effect: it defines the element as the module evaluates, so it has to run in code the browser loads. To register explicitly instead — to control the timing, or to define into another window — call the function from the matching define/ entry point, which registers nothing on its own:

Explicit registration

import { defineRangeFieldElement } from '@timelessui/components/define/ui-range-field'
defineRangeFieldElement()

Anatomy

Parts are authored in your own markup and identified by the selector below, so your CSS can target the same anatomy without loading Timeless styles. Required parts must be present for the component to work. Private data-ui-internal-* hooks are written by the runtime and must never be authored.

<ui-range-field>

Part	Required	Selector	Purpose
track	Yes	[data-ui-part~='track']	Wrapper around the two thumbs. It is the shared track: both inputs stack inside it, and the fill between them is drawn on it from measured bounds.
from	Yes	input[type='range']	The lower thumb, a native range input. Give it its own name, min, max, step, and accessible name; it submits and resets on its own, with no JavaScript.
to	Yes	input[type='range']	The upper thumb. Same contract as from, with its own name so the pair submits as two entries.
output	No	[data-ui-part~='output']	Live readout of the pair. Timeless writes the current values into it as text, so omit the part when you want to format them yourself.

ui-field

Part	Required	Selector	Purpose
control	No	[data-ui-part~='control']	Wrapper around the native control when one is needed.

Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes are presence-based: author the attribute with no value, or omit it.

ui-field

Attribute	Values	Default	Description
data-ui-layout	stacked · inline	stacked	Whether the label sits above the control or beside it.
data-ui-density	compact · normal · spacious	normal	Gap between label, control, description, and error.

Element API

Attributes above are the authoring surface. These are the DOM properties and events the registered element adds once it upgrades.

<ui-range-field>

This element adds no public properties. Configure it with its attributes.

Event	Detail	Description
ui-change	CustomEvent<RangeFieldChangeDetail>	Dispatched after either thumb moves, carrying the clamped pair and which thumb moved. Bubbles and is composed.

State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through the selectors below rather than adding your own state classes.

State	Source	How to express it
disabled	native	Native disabled on either thumb.
invalid	aria	Set aria-invalid="true" on the control and point aria-describedby at the error part.

Styling

Root identity: ui-range-field, ui-field, ui-label, ui-description. Required stylesheets: tokens.css, core/forms.css, core/range-field.css, themes/atmosphere/tokens.css, themes/atmosphere/forms.css, themes/atmosphere/range-field.css.

Set these custom properties to restyle the component:

Custom property	Controls
--ui-range-track	Track thickness.
--ui-range-thumb	Thumb diameter.
--ui-range-fill	Colour of the filled span between the two thumbs.

Design tokens this component reads (27)

These are global Atmosphere tokens. Change them once at the theme level rather than per component.

--ui-accent · --ui-bg-control · --ui-bg-control-muted · --ui-bg-surface · --ui-bg-surface-subtle · --ui-danger · --ui-danger-soft · --ui-disabled-opacity · --ui-duration-fast · --ui-ease-standard · --ui-fg · --ui-fg-muted · --ui-fg-subtle · --ui-focus · --ui-font-mono · --ui-line · --ui-line-strong · --ui-radius-md · --ui-radius-pill · --ui-radius-sm · --ui-shadow-control · --ui-shadow-inset · --ui-space-1 · --ui-space-2 · --ui-space-3 · --ui-space-4 · --ui-space-5

Accessibility

Keep the native elements, roles, and relationships shown in the example. Timeless adds only the state and keyboard coordination the platform does not already provide, and it never supplies your accessible names — those depend on your content.

Follows the Slider (Multi-Thumb) pattern from the ARIA Authoring Practices Guide.

Key	Action
Arrow keys, Home / End, Page Up / Page Down	Move the focused thumb. Handled by the native range input, not by Timeless.

Each thumb is a native input[type=range] and therefore its own tab stop, with its own accessible name and its own value announcement. Timeless only keeps the pair ordered: a thumb stops at its neighbour rather than swapping with it, so the key you are holding never starts moving the other thumb.

Verify in context

Automated checks cover axe WCAG 2.2 A and AA rules on every documented route. Keyboard, zoom, forced-colors, and screen-reader review still belong to your application.

Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

More examples

Open Range Field in StoryLite for variants, controls, and manual testing.