Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/amcharts/amcharts5/llms.txt

Use this file to discover all available pages before exploring further.

The ZoomControl provides interactive buttons for zooming and panning map charts. It includes zoom in, zoom out, and home buttons.

​
Basic Setup

Add a zoom control to your map: 
import * as am5map from "@amcharts/amcharts5/map";

const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    projection: am5map.geoMercator()
  })
);

const zoomControl = chart.set(
  "zoomControl",
  am5map.ZoomControl.new(root, {})
);
See ZoomControl.ts:15-20 and MapChart.ts:178-182

​
Showing the Home Button

Enable the home button to allow users to reset the map view: 
const zoomControl = am5map.ZoomControl.new(root, {});
chart.set("zoomControl", zoomControl);

zoomControl.homeButton.set("visible", true);
The home button resets the map to its initial position and zoom level.

​
Zoom Settings

Configure zoom behavior on the MapChart:

​
Zoom Levels

const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    projection: am5map.geoMercator(),
    zoomLevel: 1,        // Current zoom level
    minZoomLevel: 1,     // Minimum zoom (fully zoomed out)
    maxZoomLevel: 32,    // Maximum zoom (fully zoomed in)
    zoomStep: 2          // Multiplier for zoom in/out
  })
);
See MapChart.ts:40-95 Settings:
  • zoomLevel - Current zoom level (default: 1)
  • minZoomLevel - Lowest allowed zoom (default: 1)
  • maxZoomLevel - Highest allowed zoom (default: 32)
  • zoomStep - Zoom factor when using controls (default: 2)

​
Home Position

Define the initial position the home button returns to: 
const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    projection: am5map.geoMercator(),
    homeZoomLevel: 1,
    homeGeoPoint: { longitude: 0, latitude: 0 }
  })
);
See MapChart.ts:185-210 Settings:
  • homeZoomLevel - Zoom level to return to
  • homeGeoPoint - Geographic center point
  • homeRotationX - X rotation for home position
  • homeRotationY - Y rotation for home position

​
Programmatic Zoom Control

​
Zoom In/Out

Control zoom programmatically: 
// Zoom in
chart.zoomIn();

// Zoom out
chart.zoomOut();

// Go to home position
chart.goHome();
See MapChart.ts:1421-1430 and MapChart.ts:710-718

​
Zoom to Point

Zoom to a specific screen point: 
chart.zoomToPoint(
  { x: 100, y: 100 },  // Screen coordinates
  4,                    // Zoom level
  true,                 // Center on point
  1000                  // Animation duration (ms)
);
See MapChart.ts:1192-1234

​
Zoom to Geographic Point

Zoom to specific coordinates: 
chart.zoomToGeoPoint(
  { longitude: -73.935, latitude: 40.730 },  // Geographic coordinates
  8,                                          // Zoom level
  true,                                       // Center on point
  1000                                        // Animation duration (ms)
);
See MapChart.ts:1248-1258

​
Zoom to Geographic Bounds

Zoom to fit a specific geographic area: 
const bounds = {
  left: -130,
  right: -60,
  top: 50,
  bottom: 20
};

chart.zoomToGeoBounds(bounds, 1000);
See MapChart.ts:1145-1181

​
Zoom to Data Item

Zoom to a specific polygon: 
polygonSeries.mapPolygons.template.on("active", (active, target) => {
  if (target.get("active")) {
    polygonSeries.zoomToDataItem(target.dataItem);
  } else {
    chart.goHome();
  }
});

​
Pan and Zoom Behavior

​
Pan Settings

Configure how dragging affects the map: 
const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    projection: am5map.geoMercator(),
    panX: "translateX",  // Pan horizontally
    panY: "translateY"   // Pan vertically
  })
);
See MapChart.ts:98-111 Pan Options:
  • "none" - Disable panning
  • "translateX" / "translateY" - Move the map (flat projections)
  • "rotateX" / "rotateY" - Rotate the globe (spherical projections)

​
Wheel Behavior

Configure mouse wheel actions: 
const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    wheelY: "zoom",       // Vertical scroll zooms
    wheelX: "none",       // Horizontal scroll disabled
    wheelSensitivity: 1,  // Wheel sensitivity
    wheelDuration: 0      // Animation duration
  })
);
See MapChart.ts:122-161 Wheel Options:
  • "none" - Ignore wheel
  • "zoom" - Zoom in/out
  • "rotateX" / "rotateY" - Rotate the map

​
Pinch Zoom

Enable touch-based pinch zooming: 
const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    pinchZoom: true  // Enable pinch-to-zoom on touch devices
  })
);
See MapChart.ts:114-119

​
Max Pan Out

Control how far the map can be panned outside the viewport: 
const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    maxPanOut: 0.4  // 40% of map can go outside viewport
  })
);
See MapChart.ts:213-218

​
Center on Zoom Out

Automatically center the map when fully zoomed out: 
const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    centerMapOnZoomOut: true  // Auto-center at min zoom
  })
);
See MapChart.ts:221-230

​
Animation Settings

Control zoom and pan animations: 
const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    animationDuration: 1000,
    animationEasing: am5.ease.out(am5.ease.cubic)
  })
);
See MapChart.ts:163-174 Settings:
  • animationDuration - Duration in milliseconds
  • animationEasing - Easing function for smooth animations

​
Rotation Controls

For spherical projections like Orthographic: 
const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    projection: am5map.geoOrthographic(),
    panX: "rotateX",
    panY: "rotateY",
    rotationX: -100,  // Initial horizontal rotation
    rotationY: -40,   // Initial vertical rotation
    rotationZ: 0      // Initial depth rotation
  })
);

// Programmatic rotation
chart.rotate(
  -100,  // rotationX
  -40,   // rotationY
  1000   // duration
);
See MapChart.ts:59-73 and MapChart.ts:1261-1278

​
Click to Reset

Reset zoom when clicking the map background: 
const zoomControl = am5map.ZoomControl.new(root, {});
chart.set("zoomControl", zoomControl);
zoomControl.homeButton.set("visible", true);

// Click background to go home
chart.chartContainer.get("background").events.on("click", () => {
  chart.goHome();
});

​
Zoom Events

Listen to zoom level changes: 
chart.events.on("zoomLevel", (ev) => {
  console.log("Zoom level:", ev.target.get("zoomLevel"));
});

​
Styling the Control

Customize the zoom control appearance: 
const zoomControl = am5map.ZoomControl.new(root, {
  x: am5.percent(95),
  centerX: am5.percent(100),
  y: am5.percent(50),
  centerY: am5.percent(50)
});

chart.set("zoomControl", zoomControl);

// Customize buttons
zoomControl.plusButton.setAll({
  background: am5.RoundedRectangle.new(root, {
    fill: am5.color(0x3b82f6),
    fillOpacity: 0.8
  })
});

zoomControl.minusButton.setAll({
  background: am5.RoundedRectangle.new(root, {
    fill: am5.color(0x3b82f6),
    fillOpacity: 0.8
  })
});

​
Disabling Zoom Control Buttons

The zoom control automatically disables buttons when limits are reached: 
// Plus button is disabled at maxZoomLevel
// Minus button is disabled at minZoomLevel
See MapChart.ts:606-623

​
Complete Example

import * as am5 from "@amcharts/amcharts5";
import * as am5map from "@amcharts/amcharts5/map";
import am5geodata_worldLow from "@amcharts/amcharts5-geodata/worldLow";

const root = am5.Root.new("chartdiv");

const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    projection: am5map.geoMercator(),
    panX: "translateX",
    panY: "translateY",
    wheelY: "zoom",
    pinchZoom: true,
    minZoomLevel: 1,
    maxZoomLevel: 16,
    zoomStep: 2,
    homeZoomLevel: 1,
    homeGeoPoint: { longitude: 0, latitude: 0 }
  })
);

// Add zoom control with home button
const zoomControl = chart.set(
  "zoomControl",
  am5map.ZoomControl.new(root, {})
);
zoomControl.homeButton.set("visible", true);

// Add map data
const polygonSeries = chart.series.push(
  am5map.MapPolygonSeries.new(root, {
    geoJSON: am5geodata_worldLow
  })
);

// Click background to go home
chart.chartContainer.get("background").events.on("click", () => {
  chart.goHome();
});