Skip to content
ESM
import "@arcgis/map-components/components/arcgis-time-slider";
Inheritance:
ArcgisTimeSliderPublicLitElement
Since
ArcGIS Maps SDK for JavaScript 4.28

The Time Slider component simplifies visualization of temporal data in your application.

Demos

Properties

actions

Property
Type
Collection<Action>

Defines actions that will appear in a menu when the user clicks the ellipsis button timeSlider-actions-menu in the component. The ellipsis button will not display if this property is null or if the collection is empty. Each Action is defined with a unique id, a title, and an icon.

The @trigger-action event fires each time an action in the menu is clicked. This event can be used to execute custom code such as setting the timeExtent to a specific date or copying the timeExtent to the browser's clipboard.

widgets-timeSlider-actions

See also
Example
// Create a TimeSlider with two actions to snap the thumb to
// two specific time extents.
const timeSlider = new TimeSlider({
container: "timeSliderDiv",
fullTimeExtent: {
start: new Date(2011, 0, 1),
end: new Date(2012, 0, 1)
},
mode: "instant",
actions: [
{
id: "quake",
icon: "exclamation-mark-triangle",
title: "Jump to Earthquake"
},
{
id: "quake-plus-one-month",
icon: "organization",
title: "One month later"
}
]
});
// listen to timeSlider's trigger-action event
// check what action user clicked on and respond accordingly.
timeSlider.on("trigger-action", (event) => {
const quake = new Date(Date.UTC(2011, 3, 11, 8, 16, 12));
const oneMonthLater = new Date(quake.getTime()).setMonth(quake.getMonth() + 1);
switch(event.action.id) {
case "quake":
timeSlider.timeExtent = {
start: quake,
end: quake
};
break;
case "quake-plus-one-month":
timeSlider.timeExtent = {
start: oneMonthLater,
end: oneMonthLater
};
break;
}
});

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

disabled

reflected Property
Type
boolean

When true, the component is visually withdrawn and cannot receive user interaction.

Attribute
disabled
Default value
false
Example
// Create a timeslider widget that is initially disabled.
const timeSlider = new TimeSlider({
container: "timeSliderDiv",
fullTimeExtent: {
start: new Date(2000, 5, 1),
end: new Date(2010, 0, 1)
},
disabled: true
});

effectiveStops

readonly Property
Type
Array<Date> | null | undefined

Lists the specific locations on the timeline where handle(s) will snap to when manipulated.

Example
timeSlider.effectiveStops.forEach((stop) => {
console.log(stop);
});

fullTimeExtent

Property
Type
TimeExtent | null | undefined

The temporal extent of the entire slider. It defines the entire time period within which you can visualize your time aware data using the time slider component.

Example
// Create a new TimeSlider with set dates
const timeSlider = new TimeSlider({
container: "timeSliderDiv",
view: view
});
// wait for the time-aware layer to load
layer.when(() => {
// set up time slider properties based on layer timeInfo
timeSlider.fullTimeExtent = layer.timeInfo.fullTimeExtent;
timeSlider.stops = {
interval: layer.timeInfo.interval
};
});

icon

autocast Property
Type
Icon["icon"]

Icon which represents the component. Typically used when the component is controlled by another component (e.g. by the Expand component).

See also
Attribute
icon
Default value
"clock"

label

Property
Type
string

The component's default label.

Attribute
label

layout

Property
Type
TimeSliderLayout

Determines the layout used by the TimeSlider component.

Possible values are listed below:

ValueDescription
autoAutomatically uses the "compact" layout when the component width is less than 858 pixels. Otherwise the "wide" layout it used.
compactComponent elements are oriented vertically. This layout is better suited to narrower widths.
wideComponent elements are oriented laterally. This thinner design is better suited to wide applications.
Attribute
layout
Default value
"auto"
Example
timeSlider.layout = "compact";

loop

Property
Type
boolean

When true, the time slider will play its animation in a loop.

Attribute
loop
Default value
false
Example
// Start a time slider animation that advances every second
// and restarts when it reaches the end.
timeSlider.set({
loop: true,
playRate: 1000
});
timeSlider.play();

mode

Property
Type
TimeSliderMode

The time slider mode. This property is used for defining if the temporal data will be displayed cumulatively up to a point in time, a single instant in time, or within a time range. See the following table for possible values.

Possible ValuesDescriptionExample
instantThe slider will show temporal data that falls on a single instance in time. Set the timeExtent property's start and end dates to same date: {start: sameDate, end: sameDate}mode-instance
time-windowThe slider will show temporal data that falls within a given time range. This is the default. Set timeExtent property's start and date properties to desired dates.mode-instance
cumulative-from-startSimilar to time-window with the start time is always pinned to the start of the slider. Set the timeExtent property's start date to null and set end date to a desired date: {start: null, end: date}mode-instance
cumulative-from-endAlso, similar to the time-window with the end time pinned to the end of the slider. Set the timeExtent property's start date to a desired date and set end date to null: {start: date, end: null}mode-instance
See also
Attribute
mode
Default value
"time-window"
Example
// Create a single thumbed time slider that includes all historic content.
const timeSlider = new TimeSlider({
container: "timeSliderDiv",
view: view,
mode: "cumulative-from-start",
fullTimeExtent: {
start: new Date(2000, 0, 1),
end: new Date(2010, 0, 1)
},
timeExtent: {
start: null,
end: new Date(2001, 0, 1) //end date
}
});

playRate

Property
Type
number

The time (in milliseconds) between animation steps.

When a View is associated with a TimeSlider and the TimeSlider is playing, the playback will pause before advancing if the View is still updating. For example, if the playRate is set to 1,000 (one second) and the View takes 1.5 seconds to render then the TimeSlider thumb(s) will advance every 1.5 seconds rather than every second.

Attribute
play-rate
Default value
1000
Example
// Start a time slider animation that advances
// ten times a second and stops when it reaches the end.
timeSlider.set({
loop: false,
playRate: 100
});
timeSlider.play();

referenceElement

Property
Type
ArcgisReferenceElement | string | undefined

By assigning the id attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.

See also
Attribute
reference-element

state

readonly Property
Type
TimeSliderState

The current state of the component.

Default value
"disabled"
Example
// Display the current state of the view model.
switch (timeSlider.viewModel.state) {
case "disabled":
console.log("The view is not ready or some property are not set.");
break;
case "ready":
console.log("The time slider is ready for use.");
break;
case "playing":
console.log("The time slider is currently animating.");
break;
}

stops

Property
Type
Stops | null | undefined

Defines specific locations on the time slider where thumbs will snap to when manipulated. If unspecified, ten evenly spaced stops will be added.

For continuous sliding, set stops to null:

timeSlider.stops = null;

To define regularly spaced stops, parse an object with interval and timeExtent properties with types TimeInterval and TimeExtent respectively. The timeExtent property is optional and used to confine stops to a certain date range. This property is useful to commence stops on a specific day of the week or month. If a stop definition by interval results in excess of 10,000 stops, then the view model will default to ten evenly spaced stops.

// Add yearly intervals starting from the beginning of the TimeSlider.
timeSlider.stops = {
interval: {
value: 1,
unit: "years"
}
};

Rather than setting the stops as time intervals, the TimeSlider can be divided into evenly spaced stops using the count property. Similar to the previous method, divisions can be confined to a specific date range using the optional timeExtent property.

// Add stops at 15 evenly spaced intervals.
timeSlider.stops = {
count: 15
};

For irregularly spaced stops, simply assign an array of dates as demonstrated below.

// Add nine irregular stops.
timeSlider.stops = {
dates: [
new Date(2000, 0, 1), new Date(2001, 3, 8), new Date(2002, 0, 10),
new Date(2003, 12, 8), new Date(2004, 2, 19), new Date(2005, 7, 5),
new Date(2006, 9, 11), new Date(2007, 11, 21), new Date(2008, 1, 10)
]
};

Lastly, to constrain or offset division by count or interval use the optional timeExtent property.

// Add yearly stops from Christmas 2019 to Christmas 2029 only
timeSlider.stops = {
interval: {
value: 1,
unit: "years"
},
timeExtent: {
start: new Date(2019, 11, 25),
end: new Date(2029, 11, 25)
}
};
// Likewise, add stops that represent quarters of 2019 only.
timeSlider.stops = {
count: 4,
timeExtent: {
start: new Date(2019, 0, 1),
end: new Date(2020, 0, 1)
}
};
Default value
{ count : 10 }

tickConfigs

Property
Type
Array<TickConfig> | null | undefined

When set, overrides the default TimeSlider ticks labelling system. Please refer to TickConfig for detailed documentation on how to configure tick placement, style, and behavior.

Examples
// By default in "en-US" the TimeSlider will display ticks with "2010, 2011, 2012, etc".
// Overwrite TimeSlider tick configuration so that labels display "'10, '12, '14, etc" in red.
const timeSlider = new TimeSlider({
container: "timeSliderDiv",
fullTimeExtent: {
start: new Date(2010, 0, 1),
end: new Date(2020, 0, 1)
},
tickConfigs: [{
mode: "position",
values: [
new Date(2010, 0, 1), new Date(2012, 0, 1), new Date(2014, 0, 1),
new Date(2016, 0, 1), new Date(2018, 0, 1), new Date(2020, 0, 1)
].map((date) => date.getTime()),
labelsVisible: true,
labelFormatFunction: (value) => {
const date = new Date(value);
return `'${date.getUTCFullYear() - 2000}`;
},
tickCreatedFunction: (value, tickElement, labelElement) => {
tickElement.classList.add("custom-ticks");
labelElement.classList.add("custom-labels");
}
}]
};
// this CSS goes with the snippet above.
#timeSlider .custom-ticks {
background-color: red;
width: 1px;
height: 8px;
}
#timeSlider .custom-labels {
font-family: Georgia, 'Times New Roman', Times, serif;
font-size: 15px;
color: red;
}

timeExtent

Property
Type
TimeExtent | null | undefined

The current time extent of the time slider. This property can be watched for updates and used to update the time extent property in queries and/or the layer filters and effects. The following table shows the timeExtent values returned for each mode.

ModeThe timeExtent value
time-window{start: startDate, end: endDate}
instant{start: sameDate, end: sameDate}
cumulative-from-start{start: null, end: endDate}
cumulative-from-end{start: startDate, end: null}
Example
// Display the time extent to the console whenever it changes.
const timeSlider = new TimeSlider({
container: "timeSliderDiv",
mode: "time-window",
fullTimeExtent: {
start: new Date(2019, 2, 3),
end: new Date(2019, 2, 5)
},
timeExtent: {
start: new Date(2019, 2, 1),
end: new Date(2019, 2, 28)
}
});
reactiveUtils.watch(
() => timeSlider.timeExtent,
(timeExtent) => {
console.log("Time extent now starts at", timeExtent.start, "and finishes at:", timeExtent.end);
}
);

timeVisible

Property
Type
boolean

Shows/hides time in the display.

Attribute
time-visible
Default value
false
Example
// For time sliders with a small time extent it may be useful to display times as shown below.
const timeSlider = new TimeSlider({
container: "timeSliderDiv",
mode: "time-window",
timeVisible: true,
fullTimeExtent: {
start: new Date(2019, 2, 3),
end: new Date(2019, 2, 5)
},
timeExtent: {
start: new Date(2019, 2, 1),
end: new Date(2019, 2, 28)
}
});

timeZone

Property
Type
string

Dates and times displayed in the component will be displayed in this time zone. By default this time zone is inherited from MapView#timeZone. When a MapView is not associated with the component then the property will fallback to the system time zone.

Possible Values

ValueDescription
systemDates and times will be displayed in the timezone of the device or browser.
unknownDates and time are not adjusted for any timezone. TimeSlider will be disabled.
Specified IANA timezoneDates and times will be displayed in the specified IANA time zone. See wikipedia - List of tz database time zones.
Attribute
time-zone

view

Property
Type
MapViewOrSceneView | null | undefined

The view associated with the component.

Note: The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this view property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-time-slider component will be associated with a map or scene component rather than using the view property.

Example
// Create and then add a TimeSlider component and then listen to changes in the View's time extent.
const timeSlider = new TimeSlider({
container: "timeSliderDiv",
view: view,
mode: "instant",
fullTimeExtent: {
start: new Date(2000, 0, 1),
end: new Date(2010, 0, 1)
},
timeExtent: {
start: new Date(2000, 0, 1),
end: new Date(2000, 0, 1)
}
});
view.ui.add(timeSlider, "top-left");
reactiveUtils.watch(
() => view.timeExtent,
(timeExtent) => {
console.log("New view time is: ", timeExtent.start);
}
);

Methods

MethodSignature
applyTimeSliderSettings(settings: TimeSliderSettings): Promise<void>
componentOnReady
inherited
componentOnReady(): Promise<this>
destroy(): Promise<void>
next(): Promise<void>
play(): Promise<void>
previous(): Promise<void>
stop(): Promise<void>
updateWebDocument(webmap: WebMap): Promise<void>

applyTimeSliderSettings

Method
Signature
applyTimeSliderSettings (settings: TimeSliderSettings): Promise<void>
Parameters
ParameterTypeDescriptionRequired
settings
Returns
Promise<void>

componentOnReady

inherited Method
Signature
componentOnReady (): Promise<this>
Inherited from: PublicLitElement

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

Returns
Promise<this>
Example
const arcgisTimeSlider = document.querySelector("arcgis-time-slider");
document.body.append(arcgisTimeSlider);
await arcgisTimeSlider.componentOnReady();
console.log("arcgis-time-slider is ready to go!");

destroy

Method
Signature
destroy (): Promise<void>

Permanently destroy the component.

Returns
Promise<void>

next

Method
Signature
next (): Promise<void>
Returns
Promise<void>

play

Method
Signature
play (): Promise<void>
Returns
Promise<void>

previous

Method
Signature
previous (): Promise<void>
Returns
Promise<void>

stop

Method
Signature
stop (): Promise<void>
Returns
Promise<void>

updateWebDocument

Method
Signature
updateWebDocument (webmap: WebMap): Promise<void>
Parameters
ParameterTypeDescriptionRequired
webmap
Returns
Promise<void>

Events

NameType
CustomEvent<{ name: "effectiveStops" | "fullTimeExtent" | "timeExtent" | "state"; }>

arcgisPropertyChange

Event
arcgisPropertyChange: CustomEvent<{ name: "effectiveStops" | "fullTimeExtent" | "timeExtent" | "state"; }>

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

bubbles composed cancelable

arcgisReady

Event
arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready to be interacted with.

bubbles composed cancelable

arcgisTriggerAction

Event

Emitted when an action is triggered on the component.

bubbles composed cancelable