Skip to content
amCharts 5

Night series

NightSeries shades the part of a map where it is night, fading through twilight at the edge, and shows the sun where it is directly overhead.

Adding series

Section titled “Adding series”

Add the night series after the series it should shade, and tell it what time to show with sunDate:

let polygonSeries = chart.series.push(
  am5map.MapPolygonSeries.new(root, {
    geoJSON: am5geodata_worldLow
  })
);


let nightSeries = chart.series.push(
  am5map.NightSeries.new(root, {
    sunDate: "now"
  })
);

The night series works with any projection, including a globe, and does not affect how the map is fitted or zoomed.

Open in CodePen

Setting the time

Section titled “Setting the time”

sunDate can be "now", a timestamp, a date string (e.g. "2026-12-21T12:00:00Z") or a Date object. With "now", the night moves with the clock, updated every minute.

Instead of a date, we can set where the sun is directly overhead, using sunPosition. The am5map.getSunPosition() function works it out for any date:

nightSeries.set("sunPosition", am5map.getSunPosition(new Date(2026, 11, 21, 12, 0)));


// Or any point
nightSeries.set("sunPosition", { longitude: 0, latitude: 23.4 });

If both are set, sunDate wins.

Night shade

Section titled “Night shade”

The night is made of map polygons, so it is styled through mapPolygons.template. fill sets its color, and fillOpacity sets how dark full night is. By default it is black at 0.5.

nightSeries.mapPolygons.template.setAll({
  fill: am5.color(0x0b1d3a),
  fillOpacity: 0.7
});

Twilight

Section titled “Twilight”

Day turns into night across a twilight band, drawn in steps that get darker towards full night. Two settings control it:

  • twilight - width of the band, in degrees of the sun’s height above the horizon (default: 12).
  • twilightSteps - how many shades the band is drawn in (default: 4). More steps give a smoother edge.
let nightSeries = chart.series.push(
  am5map.NightSeries.new(root, {
    sunDate: "now",
    twilight: 18,
    twilightSteps: 8
  })
);

Sun

Section titled “Sun”

The series marks where the sun is directly overhead with a glowing yellow circle. On a globe, it is hidden while that point is on the far side.

The circle can be accessed with get("sun"):

nightSeries.get("sun").setAll({
  radius: 12,
  fill: am5.color(0xff6600)
});

To use something else, such as an image, set any element as sun:

nightSeries.set("sun", am5.Picture.new(root, {
  src: "sun.svg",
  width: 32,
  height: 32,
  centerX: am5.p50,
  centerY: am5.p50
}));

To hide the sun:

nightSeries.get("sun").set("forceHidden", true);

Sun above a globe

Section titled “Sun above a globe”

sunAltitude raises the sun above the map, in metres. On a globe, a raised sun floats out from the surface and stays in view a little longer as it goes round the edge.

It is for looks, not the real distance: values from 1,000,000 to 5,000,000 work well (the Earth’s radius is about 6,371,000).

let nightSeries = chart.series.push(
  am5map.NightSeries.new(root, {
    sunDate: "now",
    sunAltitude: 2000000
  })
);
Open in CodePen

With satellite images

Section titled “With satellite images”

A Map raster series can show day and night by itself, swapping in a night image of city lights. To also show the sun there, add a night series with no shade:

let rasterSeries = chart.series.push(
  am5map.MapRasterSeries.new(root, {
    src: "https://cdn.amcharts.com/lib/5/geodata/images/earthDay2048.jpg",
    nightSrc: "https://cdn.amcharts.com/lib/5/geodata/images/earthNight2048.jpg",
    sunDate: "now"
  })
);


let nightSeries = chart.series.push(
  am5map.NightSeries.new(root, {
    sunDate: "now"
  })
);


nightSeries.mapPolygons.template.set("fillOpacity", 0);

Settings

Section titled “Settings”
Setting Default Comment
sunDate Date to show the night for: "now", a timestamp, a date string or a Date. Overrides sunPosition.
sunPosition Point where the sun is directly overhead, e.g. { longitude: 0, latitude: 23.4 }.
twilight 12 Width of the twilight band, in degrees of the sun’s height.
twilightSteps 4 How many shades the twilight is drawn in.
sun Circle Element shown where the sun is overhead.
sunAltitude 0 Raises the sun above the map, in metres.