ESM
import "@arcgis/map-components/components/arcgis-daylight";
Inheritance
ArcgisDaylight→HTMLElement
Since
ArcGIS Maps SDK for JavaScript 4.28

The Daylight component can be used to manipulate the lighting conditions of an arcgis-scene. To achieve this, the component modifies the lighting property of the arcgis-scene.environment of the Scene component.

To illuminate the scene, one can either use a configuration of date and time to position the sun or switch to the virtual mode, where the light source is relative to the camera.

When illuminating the scene with sunlight and adjusting the time and date, the positions of the sun and stars are updated accordingly. This also updates the date property of the lighting of arcgis-scene.environment.

How date, time, and UTC offset work

In sunlight mode, SunLighting.date is the source of truth for the scene lighting instant. The Daylight component's utcOffset is a numeric offset from Coordinated Universal Time (UTC). It controls how that instant is displayed (date and slider time) and how user-entered local values are converted back to UTC. A UTC offset does not identify a regional time zone, such as Europe/Zurich, or automatically account for daylight saving time.

This means changing only utcOffset updates the displayed local date/time but preserves the same lighting instant. Changing localDate and/or timeSliderPosition writes a new SunLighting.date instant.

Daylight does not use arcgis-scene.timeZone. Changing the scene's time zone does not update the date and time shown in Daylight or change the lighting instant. Support for using the scene's time zone is planned for a future release.

daylight-default

The UTC offset selector, labeled Timezone in the component, sets utcOffset. Changing the selection updates the displayed date and time without changing the scene's lighting instant or arcgis-scene.timeZone. The selector can be hidden using the hideTimezone property.

By default, a calendar is displayed to select the day, month, and year. With the dateOrSeason property, the calendar can be replaced with a dropdown menu where a season can be selected instead:

daylight-seasons

There are two play buttons: one corresponds to the time-of-day slider and animates the lighting over the course of a day, while the other corresponds to the date picker and animates the lighting over the course of a year (month by month). The speed of the time-of-day animation can be set using the playSpeedMultiplier property.

Except for the daytime slider, all the elements in the Daylight component can be hidden:

daylight-no-elements

Whenever the sun position option is unchecked, the scene applies the virtual light source relative to the camera. With this, the component's time slider, UTC offset selector, and date picker get automatically disabled:

daylight-virtual

Things to consider

  • Daylight is only supported in a 3D arcgis-scene component.
  • When using the virtual light, setting the time and date programmatically does not have an influence on the lighting conditions of the scene.
  • When using the sunlight, the time slider and UTC offset react to camera changes when cameraTrackingEnabled is enabled. Camera tracking updates the simulated sun's position to maintain a consistent solar time of day as the camera moves. The component estimates the UTC offset from the camera's longitude; it does not determine the regional time zone at the camera's location.
See also

Demo

Properties

PropertyAttributeType
auto-destroy-disabled
current-season
reflected
date-or-season
"date" | "season"
day-playing
heading-level
hide-date-picker
hide-header
hide-play-buttons
hide-shadows-toggle
hide-sun-lighting-toggle
hide-timezone
reflected
icon
Icon["icon"] | undefined
label
local-date
play-speed-multiplier
reference-element
time-slider-position
time-slider-steps
utc-offset
year-playing

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-daylight auto-destroy-disabled></arcgis-daylight>
daylightElement.autoDestroyDisabled = true;

currentSeason

Property
Type
Season

Sets the season that is used when the component displays the season picker. Each season uses a fixed date corresponding to the seasonal equinoxes and solstices.

See also
Attribute
current-season

dateOrSeason

reflected Property
Type
"date" | "season"

Controls whether the component displays a date or a season picker. When the date picker is set, the user selects the date from a calendar. The season picker allows the user to choose a season from a drop-down list. Each season uses a fixed month and day corresponding to the equinoxes and solstices in the current local date's year.

Attribute
date-or-season
Default value
"date"

dayPlaying

Property
Type
boolean

Starts or pauses the daytime animation cycling through the minutes of the day. Set the property to true to start the animation and to false to pause it.

dayPlaying and yearPlaying are mutually exclusive. When virtual lighting is active, playback is stopped.

Attribute
day-playing
Default value
false

headingLevel

Property
Type
HeadingLevel

Indicates the heading level to use for the component title.

Attribute
heading-level
Default value
2

hideDatePicker

Property
Type
boolean
Attribute
hide-date-picker
Default value
false

hideHeader

Property
Type
boolean
Attribute
hide-header
Default value
false

hidePlayButtons

Property
Type
boolean
Attribute
hide-play-buttons
Default value
false

hideShadowsToggle

Property
Type
boolean
Attribute
hide-shadows-toggle
Default value
false

hideSunLightingToggle

Property
Type
boolean
Attribute
hide-sun-lighting-toggle
Default value
false

hideTimezone

Property
Type
boolean

If true, the UTC offset selector, labeled Timezone in the component, is hidden.

Attribute
hide-timezone
Default value
false

icon

reflected Property
Type
Icon["icon"] | undefined

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
"brightness"

label

Property
Type
string | undefined

The component's default label.

Attribute
label

localDate

autocast Property
Type
Date
Since
ArcGIS Maps SDK for JavaScript 4.34

The local calendar date using utcOffset.

Date-only ISO strings in YYYY-MM-DD format are preserved as-is to avoid day shifts in locations with negative UTC offsets. Other valid Date, number, and string values are normalized to canonical YYYY-MM-DD.

Attribute
local-date
Examples
daylight.localDate = "2005-08-25";
// Alternatively, the date can be set by configuring the `date` property of `SunLighting`.
viewElement.environment.lighting = new SunLighting({
date: new Date("2005-08-25T16:00:00")
});

localDateAsString

readonly Property
Type
string | undefined

playSpeedMultiplier

Property
Type
number

Controls the daytime animation speed.

Attribute
play-speed-multiplier
Default value
1.0
Example
// Plays the daylight animation at half of the default speed
daylight.playSpeedMultiplier = 0.5;

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

timeSliderPosition

Property
Type
number | null | undefined
Since
ArcGIS Maps SDK for JavaScript 4.34

Slider position for the local time of day using utcOffset. The position represents the time of day in minutes. Values are normalized to a single day (0-1439).

Attribute
time-slider-position
Examples
// Set the local time to 4:00 PM (16:00) using the component's UTC offset.
daylight.timeSliderPosition = 16 * 60;
// Alternatively, the time can be set by configuring the `date` property of `SunLighting`.
// Then, the time slider gets updated automatically.
viewElement.environment.lighting = new SunLighting({
date: new Date("2005-08-25T16:00:00")
});

timeSliderSteps

Property
Type
number[] | number

Sets the interval, in minutes, with which the time slider increments or decrements as it is dragged or changed via the keyboard.

Attribute
time-slider-steps
Default value
5
Example
// Set steps at an interval of 60. Then, the slider thumb snaps at each hour of the day.
daylight.timeSliderSteps = 60;

utcOffset

Property
Type
number | null | undefined
Since
ArcGIS Maps SDK for JavaScript 4.34

The UTC offset in hours used to display the component's local date and time. This numeric offset does not identify a regional time zone or automatically account for daylight saving time.

In sunlight mode, changing only this property preserves the current SunLighting.date instant and recomputes displayed local date/time in the new offset. When this property changes together with localDate and/or timeSliderPosition, the date/time values are applied as one local selection and a new lighting instant is written. This property is separate from arcgis-scene.timeZone. Changing one does not update the other.

Attribute
utc-offset
Examples
// Change the UTC offset while preserving the same scene lighting instant.
daylight.utcOffset = -8;
// Apply the UTC offset and local date/time together to write a new lighting instant.
daylight.utcOffset = -8;
daylight.localDate = "2025-01-15";
daylight.timeSliderPosition = 16 * 60;
// Alternatively, the UTC offset can be set by configuring the `displayUTCOffset` property of `SunLighting`.
viewElement.environment.lighting = new SunLighting({
displayUTCOffset: -8
});

view

Property
Type
SceneView | 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-daylight component will be associated with a map or scene component rather than using the view property.

yearPlaying

Property
Type
boolean

Starts or pauses the date animation cycling through the months of the year. Set the property to true to start the animation and to false to pause it.

yearPlaying and dayPlaying are mutually exclusive. When virtual lighting is active, playback is stopped.

Attribute
year-playing
Default value
false

Methods

MethodSignature
inherited
componentOnReady(): Promise<this>
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 arcgisDaylight = document.createElement("arcgis-daylight");
document.body.append(arcgisDaylight);
await arcgisDaylight.componentOnReady();
console.log("arcgis-daylight is ready to go!");

destroy

Method
Signature
destroy (): Promise<void>

Permanently destroy the component.

Returns
Promise<void>

Events

arcgisReady

Event
arcgisReady: CustomEvent<void>

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

bubbles composed cancelable

arcgisUserDateTimeChange

Event
arcgisUserDateTimeChange: CustomEvent<void>
Since
ArcGIS Maps SDK for JavaScript 4.33

Fires when the user changes the date or time in the component by interacting with the slider, the date picker, the season selector or the play buttons.

This event is user-action only. It does not fire for internal synchronization (for example, initial state sync when the view becomes ready).

bubbles composed cancelable