▾
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.
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:

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:

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:

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.
Demo
Properties
| Property | Attribute | Type |
|---|---|---|
| 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 | ||
| readonly | | |
| play-speed-multiplier | ||
| reference-element | ||
| time-slider-position | ||
| time-slider-steps | ||
| utc-offset | ||
| | ||
| year-playing |
autoDestroyDisabled
- 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
- 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
- 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
- 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
- Type
- HeadingLevel
Indicates the heading level to use for the component title.
- Attribute
- heading-level
- Default value
- 2
hideTimezone
- Type
- boolean
If true, the UTC offset selector, labeled Timezone in the component, is hidden.
- Attribute
- hide-timezone
- Default value
- false
icon
- 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"
localDate
- 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")});
playSpeedMultiplier
- 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 speeddaylight.playSpeedMultiplier = 0.5;
referenceElement
- 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.
- Attribute
- reference-element
timeSliderPosition
- 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
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
- 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
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
viewproperty 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 theviewproperty.
yearPlaying
- 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
| Method | Signature |
|---|---|
| inherited | componentOnReady(): Promise<this> |
| destroy(): Promise<void> |
componentOnReady
- 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!");
Events
arcgisReady
arcgisReady: CustomEvent<void> Emitted when the component associated with a map or scene view is ready for user interaction.
arcgisUserDateTimeChange
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).
