To source

Atrium // Elements

a-range

A customisable range slider element for selecting numeric values.

The a-range element is a fully styleable range slider for selecting numeric values within a defined range. It supports keyboard navigation, custom styling via CSS custom properties, and works as a form-associated element.

Usage

Basic Usage

<a-range value="0.5"></a-range>

With Min, Max and Step

<!-- Range from 0 to 100, stepping by 10 -->
<a-range min="0" max="100" step="10" value="50"></a-range>

Percentage Values (Default)

By default, the range operates from 0 to 1:

<a-range value="0.25"></a-range> <!-- 25% -->
<a-range value="0.5"></a-range>  <!-- 50% -->
<a-range value="0.75"></a-range> <!-- 75% -->

Listening to Value Changes

const range = document.querySelector('a-range');

range.addEventListener('input', (event) => {
  const { value } = event.detail;
  console.log('Current value:', value);
});

Reading the Value

const range = document.querySelector('a-range');

// As a number
console.log(range.valueAsNumber); // 0.5

// As the property
console.log(range.value); // 0.5

Disabled State

<a-range disabled value="0.5"></a-range>

Buffer

Use buffer to show a secondary progress from 0 to 1 behind the value, like the loaded part of a media file. It is used by a-media-seek.

<a-range value="0.3" buffer="0.6"></a-range>

Styling

The range slider is fully customisable via CSS custom properties:

a-range {
  /* Handle (the draggable circle) */
  --range-handle-background: #1d4ed8;
  --range-handle-size: 0.75rem;

  /* Progress bar (filled portion) */
  --range-progress-background: #1d4ed8;

  /* Track (unfilled portion) */
  --range-track-background: #e5e7eb;
  --range-track-height: 0.25rem;
  --range-track-padding: 0.5rem 0;

  /* Buffer (secondary progress), defaults to the track background */
  --range-buffer-background: #d1d5db;

  /* Focus state */
  --range-outline-color: #3b82f6;
}

Themed Example

<style>
  .custom-range {
    --range-handle-background: #10b981;
    --range-progress-background: #10b981;
    --range-track-background: #d1fae5;
    --range-handle-size: 1rem;
    --range-track-height: 0.5rem;
  }
</style>

<a-range class="custom-range" value="0.6"></a-range>

CSS Parts

Style internal parts directly using ::part():

a-range::part(track) {
  border-radius: 0;
}

a-range::part(handle) {
  border: 2px solid white;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
}
PartDescription
trackThe background track element
bufferThe secondary progress inside the track
handleThe draggable handle/thumb

Accessibility

  • Role: The element has role="slider" for screen reader compatibility.
  • ARIA Attributes: Automatically sets aria-valuemin, aria-valuemax, aria-valuenow, and aria-orientation.
  • Keyboard Navigation:
    • Focus is indicated with a visible outline
  • Label: Name the slider with the label attribute, it is set as aria-label.
  • Disabled State: When disabled, aria-disabled="true" is set and interactions are blocked.

Range

A simple range slider component for a single value.

Example


<a-range value="0.5"></a-range>

Attributes


Name Type Default value Description
buffer undefined undefined

Secondary progress from 0 to 1 behind the value, like the buffered part of a video.

disabled undefined undefined

Disabled state of the range.

label undefined undefined

Accessible label of the slider.

max undefined undefined

Maximum value of the range.

min undefined undefined

Minimum value of the range.

step undefined undefined

Step value of the range.

value undefined undefined

The current value of the range.

References