arcgis-time-bar-slider | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/map-components/components/arcgis-time-bar-slider";

Inheritance: ArcgisTimeBarSlider→HTMLElement

Since: ArcGIS Maps SDK for JavaScript 5.2

Configuring the Time Bar Slider
- Built-in configuration with visible UI controls
- Custom configuration with visible UI controls

The Time Bar Slider component renders an interactive time-based slider inside the Time Bar component. It can only be used in the Time Bar component's time-extent slot. Users can drag the slider thumbs to update the Time Bar's timeExtent. The Time Bar's mode determines whether the slider selects a single instant, a time window, or a cumulative range within its fullTimeExtent.

Configuring the Time Bar Slider

The Time Bar Slider is highly configurable. You can customize its appearance, behavior, and the content of its slots to suit your application's needs. Use the showMin, showMax, and showTicks properties (or their corresponding HTML attributes show-min, show-max, and show-ticks) to display optional minimum and maximum date labels and tick marks.

Time Bar Slider anatomy showing controls, attributes, and named slots

Built-in configuration with visible UI controls

The image below shows a Time Bar Slider displaying minimum and maximum date labels, tick marks, and a persistent popover. The popover displays the current date range. Time Bar Slider with popover

<arcgis-time-bar id="time-bar" show-time-extent show-play show-next show-previous format="date-time" floating>
  <arcgis-time-bar-slider
    slot="time-extent"
    show-min
    show-max
    show-ticks
    popover-display="always">
  </arcgis-time-bar-slider>
</arcgis-time-bar>

const timeBar = document.querySelector("arcgis-time-bar");
await timeBar.componentOnReady();
timeBar.fullTimeExtent = layer.timeInfo.fullTimeExtent;

Custom configuration with visible UI controls

The "min", "max", "content-end", and "popover" slots can be used to define custom content like formatted start and end dates. The following example customizes the "content-end" and "popover" slots, shows ticks every 3 days, keeps the date popover visible with popover-display="always", and uses CSS for custom styling.

Time Bar Slider with custom popover

#time-bar {
  --calcite-color-brand: #C53C06;
  --calcite-color-brand-press: #c79e42;
}
arcgis-time-bar-slider {
  block-size: 64px;
  color: var(--calcite-color-brand);
}
.time-label {
  color: var(--calcite-color-brand);
  font-size: 18px;
  font-weight: bold;
  text-align: center;
  width: max-content;
  max-width: min(280px, calc(100vw - 32px));
}

<!-- Initialize the Time Bar with ticks and a locked time window -->
<arcgis-time-bar floating show-play show-time-extent id="time-bar">
  <arcgis-time-bar-slider
    slot="time-extent"
    show-min
    show-max
    show-ticks
    show-lock-time-window
    lock-time-window
    popover-display="always">
    <arcgis-ticks slot="content-end" mode="value" show-labels> </arcgis-ticks>
    <div slot="popover" class="time-label"></div>
  </arcgis-time-bar-slider>
</arcgis-time-bar>

const timeBar = document.querySelector("arcgis-time-bar");
await timeBar.componentOnReady();
timeBar.fullTimeExtent = layer.timeInfo.fullTimeExtent;

const timeBarSlider = timeBar.querySelector("arcgis-time-bar-slider");
const ticks = timeBarSlider.querySelector("arcgis-ticks");
const popoverSlot = timeBarSlider.querySelector('[slot="popover"]');
const popoverFormatter = new Intl.DateTimeFormat(undefined, {
  month: "short",
  day: "numeric",
});

// Match the tick range to the Time Bar's full time extent
ticks.min = timeBar.fullTimeExtent.start.getTime();
ticks.max = timeBar.fullTimeExtent.end.getTime();
const tickValues = [];

// Add a tick every three days
for (const date = new Date(ticks.min); date.getTime() <= ticks.max; date.setDate(date.getDate() + 3)) {
  tickValues.push(date.getTime());
}
ticks.values = tickValues;

const tickDateFormatter = new Intl.DateTimeFormat(undefined, { month: "numeric", day: "numeric" });
ticks.labelFormatter = (value) => tickDateFormatter.format(new Date(value));

// Display the selected date range in the slider's popover
function updatePopover() {
  const { start, end } = timeBar.timeExtent;
  popoverSlot.textContent = popoverFormatter.formatRange(start, end);
}

timeBar.addEventListener("arcgisPropertyChange", async (event) => {
  if (event.detail.name === "timeExtent") {
    updatePopover();
  }
});

See also

Properties

Property	Attribute	Type
activeValue readonly		Date \| TimeExtent \| null \| undefined
autoDestroyDisabled	auto-destroy-disabled	boolean
lockTimeWindow	lock-time-window	boolean
popoverDisplay	popover-display	PopoverDisplay
showLockTimeWindow	show-lock-time-window	boolean
showMax	show-max	boolean
showMin	show-min	boolean
showTicks	show-ticks	boolean

activeValue

readonly Property

Type: Date | TimeExtent | null | undefined

This property is intended to be used when inserting an element in the "popover" slot. This property will return either undefined, a Date or a TimeExtent depending on popoverDisplay and user interaction.

When popover-display is set to:

"none", this property will always return undefined.
"always", this property will always return arcgis-time-bar.timeExtent.
"auto", this property will either return a Date if the user is interacting with a slider thumb, or arcgis-time-bar.timeExtent if the user is interacting with a slider track, or undefined if the user is not interacting with either a slider thumb or slider track.

Example

The following example demonstrates how to use the activeValue property to update custom popover content during user interaction:

Dragging a thumb: Displays the day of the week for that specific thumb's position.
Dragging the track: Displays the days of the week for the start and end of the active time range.

The following code listens for changes to activeValue and updates the popover content.

<arcgis-map basemap="satellite" zoom="6" center="-2,54">
  <arcgis-time-bar show-play show-next show-previous show-time-extent slot="top-right">
    <arcgis-time-bar-slider slot="time-extent" popover-display="auto">
      <div slot="popover" style="color: red; font-weight: bold; text-align: center; width: 100px;"></div>
    </arcgis-time-bar-slider>
  </arcgis-time-bar>
</arcgis-map>

const timeBar = document.querySelector("arcgis-time-bar");
await timeBar.componentOnReady();
const timeBarSlider = document.querySelector("arcgis-time-bar-slider");
const popoverSlot = timeBarSlider.querySelector('[slot="popover"]');

timeBar.fullTimeExtent = new TimeExtent({
  start: new Date(2026, 5, 22),
  end: new Date(2026, 5, 26),
});
timeBar.stops = {
  interval: new TimeInterval({
    value: 1,
    unit: "days",
  }),
};

timeBarSlider.addEventListener("arcgisPropertyChange", (event) => {
  if (event.detail.name === "activeValue") {
    const activeValue = timeBarSlider.activeValue;

    if (!activeValue) {
      popoverSlot.innerHTML = "";
    } else if (activeValue instanceof Date) {
      popoverSlot.innerHTML = activeValue.toLocaleDateString(undefined, { weekday: "long" });
      popoverSlot.style.width = "100px";
    } else if (activeValue instanceof TimeExtent) {
      const start = activeValue.start?.toLocaleDateString(undefined, { weekday: "long" });
      const end = activeValue.end?.toLocaleDateString(undefined, { weekday: "long" });
      popoverSlot.innerHTML = `${start} - ${end}`;
      popoverSlot.style.width = "150px";
    }
  }
});

autoDestroyDisabled

Property

Type: boolean

If true, the component will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the component to a different place on the page, or temporarily hide it. If this is set, make sure to call the destroy() method when you are done to prevent memory leaks.

Attribute: auto-destroy-disabled
Default value: false

Example

<arcgis-time-bar-slider auto-destroy-disabled></arcgis-time-bar-slider>

timeBarSliderElement.autoDestroyDisabled = true;

lockTimeWindow

Property

Type: boolean

When true and the Time Bar is in time-window mode, users will not be able to adjust individual thumbs. The thumbs remain a fixed number of stops apart. This ensures that the time window behaves as a single unit rather than allowing individual thumbs to be moved independently. This property can be toggled by the user if the showLockTimeWindow property is true.

See also

Time Bar Slider custom configuration

Attribute: lock-time-window
Default value: false

popoverDisplay

Property

Type: PopoverDisplay

Defines how and when popovers are displayed for the slider's thumb or range.

When none, popovers are not displayed.
When auto, popovers are displayed automatically when the user interacts with a thumb or the slider's range.
When always, popovers are always displayed. If the slider is in time-window mode, popovers are displayed for the slider range; otherwise, they are displayed for the thumb.

Attribute: popover-display
Default value: "none"

showLockTimeWindow

Property

Type: boolean

When true, the Time Bar component will display a button to toggle the value of the lockTimeWindow property.

The button will appear depressed when lockTimeWindow is true.
The button will appear disabled when the mode is not time-window.

Attribute: show-lock-time-window
Default value: false

showMax

Property

Type: boolean

When true, displays the slot at the end of the Time Bar Slider. By default, the slotted element contains a label for the end date of the Time Bar's fullTimeExtent. Provide an element in the "max" slot to replace the default label.

Attribute: show-max
Default value: false

showMin

Property

Type: boolean

When true, displays the slot at the start of the Time Bar Slider. By default, the slotted element contains a label for the start date of the Time Bar's fullTimeExtent. Provide an element in the "min" slot to replace the default label.

Attribute: show-min
Default value: false

showTicks

Property

Type: boolean

When true, displays tick marks and labels beneath the slider.

Attribute: show-ticks
Default value: false

Methods

Method	Signature
componentOnReady inherited	componentOnReady(): Promise<this>
destroy	destroy(): Promise<void>

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisTimeBarSlider = document.createElement("arcgis-time-bar-slider");
document.body.append(arcgisTimeBarSlider);
await arcgisTimeBarSlider.componentOnReady();
console.log("arcgis-time-bar-slider is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

Events

Name	Type
arcgisPropertyChange	CustomEvent<{ name: "activeValue" \| "lockTimeWindow"; }>
arcgisReady	CustomEvent<void>

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "activeValue" | "lockTimeWindow"; }>

Emitted when the value of a property is changed. Use this to listen to changes to properties.

arcgisReady

Event

arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready for user interaction.

Slots

Name	Description
content-end	A slot that displays content directly below the slider, typically a Ticks component with custom tick positions and labels. If unused, the default Ticks component will be displayed.
max	A slot at the end of the Time Bar Slider. If unused, a label with the slider's end date will be displayed.
min	A slot that displays a label at the start of the Time Bar Slider. If unused, a label with the slider's start date will be displayed.
popover	A slot that displays a popover's content while interacting with the slider's thumb or range. If not provided, current time extent dates will be rendered. To display a Time Bar Slider's popover, the popoverDisplay property or `"popover-display"` attribute must be set to either `auto` or `always`.

content-end

Slot

A slot that displays content directly below the slider, typically a Ticks component with custom tick positions and labels. If unused, the default Ticks component will be displayed.

See also

max

Slot

A slot at the end of the Time Bar Slider. If unused, a label with the slider's end date will be displayed.

See also

min

Slot

A slot that displays a label at the start of the Time Bar Slider. If unused, a label with the slider's start date will be displayed.

See also

Time Bar Slider custom configuration

Slot

A slot that displays a popover's content while interacting with the slider's thumb or range. If not provided, current time extent dates will be rendered. To display a Time Bar Slider's popover, the popoverDisplay property or "popover-display" attribute must be set to either auto or always.

See also

Time Bar Slider custom configuration