Skip to content
amCharts 5

IMapChartSettings

Type interface

Sources

IMapChartSettings is an interface: it describes a shape of data and is not imported on its own.

Inheritance

IMapChartSettings extends ISerialChartSettings.

IMapChartSettings is not extended by any other symbol.

Properties

animationDuration

Type undefined | number

Duration of zoom and rotation animations, in milliseconds: zooming with the wheel, buttons or a double click, and the zoom and rotate methods.

animationEasing

Type undefined | (t: Time) => TimeDefault am5.ease.out(am5.ease.cubic)

Easing of zoom and rotation animations.

More info: Animations: easing functions

autoHome

Type undefined | false | trueDefault falseSince 5.21.0

Goes to the home position once the map is loaded, as goHome() does:

animated when animationDuration is set (as by the Animated theme), at once otherwise.

boxZoom

Type "none" | "drag" | "shift" | "ctrl" | "alt"Default "none"Since 5.20.2

Zooms the map to a box drawn with the pointer, while this key is held:

"drag" needs no key. A plain drag pans the map, so use "drag" with panX and panY set to "none".

The box is drawn with boxZoomSelection.

centerMapOnZoomOut

Type undefined | false | trueDefault trueSince 5.2.1

Centers the map on its home point (homeGeoPoint, or the middle of the map) whenever it zooms to homeZoomLevel, such as when fully zoomed out.

Otherwise zooming out keeps the point under the pointer, or the middle of the view, in place.

doubleClickZoom

Type undefined | false | trueDefault trueSince 5.20.2

Zooms the map in by zoomStep on a double click or double tap, and out on Shift + double click.

On a map panned by rotating (panX: "rotateX" or panY: "rotateY"), the clicked location turns to the middle. Otherwise it stays under the pointer.

homeGeoPoint

Type IGeoPoint

The point goHome() and autoHome center the map on. If not set, the middle of the map is used.

More info: Panning and zooming the map: initial position and zoom

homeRotationX

Type undefined | number

rotationX of the home position, which goHome() and autoHome go to.

More info: Panning and zooming the map: initial position and zoom

homeRotationY

Type undefined | number

rotationY of the home position, which goHome() and autoHome go to.

More info: Panning and zooming the map: initial position and zoom

homeZoomLevel

Type undefined | numberDefault 1

Zoom level of the home position, which goHome() and autoHome go to.

More info: Panning and zooming the map: initial position and zoom

maxPanOut

Type undefined | numberDefault 0.4

How far the map can be dragged away from the middle, as a share of its size: 0.4 lets its center move 40% of the map's width or height. A map zoomed larger than the chart can always be dragged to its edges.

More info: Panning and zooming the map: panning outside viewport

maxZoomLevel

Type undefined | numberDefault 32

The highest zoom level the map can zoom in to.

minZoomLevel

Type undefined | numberDefault 1

The lowest zoom level the map can zoom out to.

panX

Type "none" | "rotateX" | "translateX"Default "translateX"

What dragging the map horizontally does: "translateX" moves it, "rotateX" turns it around the poles (as on a globe), "none" nothing.

More info: Panning and zooming the map: panning

panY

Type "none" | "rotateY" | "translateY"Default "translateY"

What dragging the map vertically does: "translateY" moves it, "rotateY" tilts it north or south (as on a globe), "none" nothing.

More info: Panning and zooming the map: panning

pinchZoom

Type undefined | false | trueDefault true

Lets users zoom the map with a two-finger pinch on touch devices.

More info: Panning and zooming the map: pinch zoom

projection

Type GeoProjection

The projection the map is drawn with, such as am5map.geoMercator().

More info: Map chart: projections

projectionName

Type undefined | stringSince 5.19.0

The projection by name, such as "geoOrthographic": the chart sets projection to it. Useful in JSON configs, which can't hold a function.

The names "geoMercator", "geoOrthographic", "geoEquirectangular", "geoAlbersUsa", "geoEqualEarth" and "geoNaturalEarth1" work out of the box. Register any other projection once, before creating the chart:

import { geoConicConformal } from "d3-geo";
am5map.registerProjection("geoConicConformal", geoConicConformal);

am5map.registerProjection("geoConicConformal", d3.geoConicConformal);
rotationX

Type undefined | numberDefault 0

Turns the map around the poles, in degrees: the longitude -rotationX comes to the middle, so -74 centers longitude 74. Needs a projection that can rotate.

More info: Map chart: centering the map

rotationY

Type undefined | numberDefault 0

Tilts the map north or south, in degrees: the latitude -rotationY comes to the middle, so -30 centers latitude 30. Needs a projection that can rotate.

More info: Map chart: centering the map

rotationZ

Type undefined | numberDefault 0

Spins the map around its middle, in degrees. Needs a projection that can rotate.

More info: Map chart: centering the map

translateX

Type undefined | number

Horizontal position of the projection's center, in pixels from the left of the map's area. Changes as the map is panned.

translateY

Type undefined | number

Vertical position of the projection's center, in pixels from the top of the map's area. Changes as the map is panned.

wheelDuration

Type undefined | numberDefault 0

Duration of the rotation a wheel turn makes, in milliseconds. Applies only to the "rotateX" and "rotateY" wheel actions.

wheelEasing

Type undefined | (t: Time) => TimeDefault am5.ease.out(am5.ease.cubic)

Easing of the rotation a wheel turn makes. Applies only to the "rotateX" and "rotateY" wheel actions.

More info: Animations: easing functions

wheelSensitivity

Type undefined | numberDefault 1

Multiplies how far the wheel rotates the map. Applies only to the "rotateX" and "rotateY" wheel actions.

wheelX

Type "none" | "zoom" | "rotateX" | "rotateY"Default "none"

What scrolling horizontally (with a tilting wheel or a touchpad) does to the map.

More info: Panning and zooming the map: mouse wheel behavior

wheelY

Type "none" | "zoom" | "rotateX" | "rotateY"Default "zoom"

What turning the mouse wheel does to the map.

More info: Panning and zooming the map: mouse wheel behavior

zoomControl

Type ZoomControl

Zoom buttons to show on the map.

More info: Map chart: zoom control

zoomLevel

Type undefined | numberDefault 1

The map's zoom level: 1 shows the whole map fitted to the chart, 2 shows it twice as large.

zoomStep

Type undefined | numberDefault 2

How many times one zoom step zooms in or out: the zoom level is multiplied or divided by it. Used by ZoomControl, the wheel, double clicks, zoomIn() and zoomOut().

99 inherited items
active

Type undefined | false | trueInherited from ISpriteSettings

Applies the element's "active" state while true.

animations

Type ArrayInherited from IEntitySettingsSince 5.20.8

Animations the element plays on its own, described as data - so they can be set from a JSON config and saved with it.

Each one animates a setting of the element (or, with target: "dataItem", a value of its data item - a map point's positionOnLine, say). They start when the setting is applied, restart when it changes, and stop when the element is disposed. A saved config keeps what was configured, never a value caught half way through an animation.

sprite.set("animations", [
  { key: "rotation", to: 360, duration: 4000, loops: 0 },
  { key: "scale", from: 1, to: 1.3, duration: 800, loops: 0, yoyo: true, easing: "sine" }
]);
appearDelay

Type undefined | numberDefault 0Inherited from ISpriteSettingsSince 5.21.0

Milliseconds to wait before the autoAppear animation starts. The element stays hidden until then.

appearDuration

Type undefined | numberInherited from ISpriteSettingsSince 5.21.0

Duration of the autoAppear animation, in milliseconds. Without it, the element's stateAnimationDuration is used.

ariaChecked

Type undefined | false | trueInherited from ISpriteSettings

aria-checked setting.

This setting is ignored unless role is one of the following:

  • "checkbox"

  • "option"

  • "radio"

  • "menuitemcheckbox"

  • "menuitemradio"

  • "treeitem" On a toggle "button" (one with toggleKey) it is exposed as aria-pressed.

ariaControls

Type undefined | stringInherited from ISpriteSettings

aria-controls setting.

ariaCurrent

Type undefined | stringInherited from ISpriteSettingsSince 5.9.8

aria-current setting.

More info: https://w3c.github.io/aria/#aria-current

ariaExpanded

Type undefined | false | trueInherited from ISpriteSettingsSince 5.21.0

aria-expanded setting: whether the content the element shows or hides (e.g. a task's subtasks, a node's children) is shown.

More info: https://w3c.github.io/aria/#aria-expanded

ariaHidden

Type undefined | false | trueInherited from ISpriteSettings

aria-hidden setting.

ariaLabel

Type undefined | stringInherited from ISpriteSettings

Label for the element to use for screen readers.

More info: Accessibility: screen reader

ariaLive

Type AriaLiveInherited from ISpriteSettings

aria-live setting.

ariaOrientation

Type undefined | stringInherited from ISpriteSettings

aria-orientation setting.

ariaSelected

Type undefined | false | trueInherited from ISpriteSettingsSince 5.9.8

aria-selected setting.

More info: https://w3c.github.io/aria/#aria-selected

ariaValueMax

Type undefined | stringInherited from ISpriteSettings

aria-valuemax setting.

ariaValueMin

Type undefined | stringInherited from ISpriteSettings

aria-valuemin setting.

ariaValueNow

Type undefined | stringInherited from ISpriteSettings

aria-valuenow setting.

ariaValueText

Type undefined | stringInherited from ISpriteSettings

aria-valuetext setting.

autoAppear

Type undefined | false | trueDefault falseInherited from ISpriteSettingsSince 5.21.0

Plays the element's reveal animation, as appear() does, when it is first drawn: a chart fades in, a series grows its columns or lines from the base. A series waits for its first data. It plays once: data updates do not replay it, but turning the setting off and on again does.

Elements made from a template play as each one is made.

An element that starts hidden (visible: false, or hidden in code before it is drawn) stays hidden. An animations entry on the same setting, such as a pulsing opacity, keeps playing.

This is how a JSON config gets the opening animation, as a config cannot call appear().

chart.setAll({ autoAppear: true, appearDuration: 1000, appearDelay: 100 });
series.setAll({ autoAppear: true, appearDuration: 1000 });

chart.setAll({ autoAppear: true, appearDuration: 1000, appearDelay: 100 });
series.setAll({ autoAppear: true, appearDuration: 1000 });

More info: Animations

background

Type GraphicsInherited from IContainerSettings

Element drawn behind the container's content, sized to fill the container.

More info: Containers: background

blur

Type undefined | numberInherited from ISpriteSettingsSince 5.5.0

Blur radius in pixels, from 0 (no blur) up.

IMPORTANT: This setting is not supported in Safari browsers.

More info: Filters

brightness

Type undefined | numberInherited from ISpriteSettingsSince 5.5.0

Brightness.

  • 0 - completely black

  • 1 - no changes (default)

  • >1 - brighter IMPORTANT: This setting is not supported in Safari browsers.

More info: Filters

centerX

Type number | PercentInherited from ISpriteSettings

The point of the element that is placed at its x position, and that it rotates and scales around: pixels from its left edge, or a percent of its width.

centerY

Type number | PercentInherited from ISpriteSettings

The point of the element that is placed at its y position, and that it rotates and scales around: pixels from its top edge, or a percent of its height.

clickAnnounceText

Type undefined | stringInherited from ISpriteSettingsSince 5.10.8

If set, the text will be read out (announced) by a screen reader when focused element is "clicked" (by pressing ENTER or SPACE).

colors

Type ColorSetInherited from ISerialChartSettings

The ColorSet series take their colors from.

More info: XY chart series: series colors

contrast

Type undefined | numberInherited from ISpriteSettingsSince 5.5.0

Contrast.

  • 0 - completely gray

  • 1 - no changes (default)

  • >1 - more contrast IMPORTANT: This setting is not supported in Safari browsers.

More info: Filters

crisp

Type undefined | false | trueDefault falseInherited from ISpriteSettingsSince 5.3.0

Draws the element sharply, with minimal anti-aliasing: its position is rounded to whole pixels, and strokeWidth is adjusted to the device pixel ratio, so lines may look thinner than expected.

NOTE: it may not work well on several elements that are meant to fit together exactly.

cursorOverStyle

Type undefined | stringInherited from ISpriteSettings

CSS cursor to show while the pointer is over the element, e.g.

"pointer".

More info: https://developer.mozilla.org/en-US/docs/Web/CSS/cursor

dateFormatter

Type DateFormatter | undefinedInherited from ISpriteSettings

A DateFormatter to use for this element instead of the root's.

More info: /v5/concepts/using-formatters/

disabled

Type undefined | false | trueInherited from ISpriteSettings

Applies the element's "disabled" state while true. It changes only the look: the element still responds to the pointer.

draggable

Type undefined | false | trueInherited from ISpriteSettings

Lets the user drag the element. Touches that start on it no longer scroll the page.

durationFormatter

Type DurationFormatter | undefinedInherited from ISpriteSettings

A DurationFormatter to use for this element instead of the root's.

More info: /v5/concepts/using-formatters/

dx

Type undefined | numberInherited from ISpriteSettings

Horizontal shift in pixels. Can be negative to shift leftward.

dy

Type undefined | numberInherited from ISpriteSettings

Vertical shift in pixels. Can be negative to shift upward.

exportable

Type undefined | false | trueInherited from ISpriteSettings

If false, the element is left out of exported images of the chart.

focusable

Type undefined | false | trueInherited from ISpriteSettings

Can element be focused, i.e. selected using TAB key.

More info: Accessibility: focusing elements

focusableGroup

Type string | numberInherited from ISpriteSettingsSince 5.0.6

An identifier by which to group common elements into focusable groups.

If set, only the first element in he group will be focusable via TAB key.

When it is selected, the rest of the elements in the same group can be selected using arrow keys.

It allows users to TAB-through chart elements quickly without the need to TAB into each and every element.

It's up to implementer of the charts to provide meaningful ariaLabel to the element, which advertises this capability and provides adequate instructions.

More info: Accessibility: grouping focusable elements

forceHidden

Type undefined | false | trueInherited from ISpriteSettings

Hides the element whatever its visible setting, even when show() is called.

forceInactive

Type undefined | false | trueInherited from ISpriteSettingsSince 5.0.21

Makes the element and its children ignore the pointer, even with interactive: true or event listeners set.

height

Type number | Percent | nullInherited from ISpriteSettings

Height in pixels, or a Percent of the parent's inner height. In a vertical layout, a percent height is a share of the height the other children leave.

hoverOnFocus

Type undefined | false | trueInherited from ISpriteSettings

Simulate hover on an element when it gains focus, including changing hover appearance and displaying a tooltip if applicable.

More info: Accessibility: focusing elements

html

Type undefined | stringInherited from IContainerSettingsSince 5.2.11

HTML content of the container. It can hold data placeholders, such as {category}.

More info: HTML content

hue

Type undefined | numberInherited from ISpriteSettingsSince 5.5.0

Rotates the hue of all colors by this many degrees, from 0 to 360.

IMPORTANT: This setting is not supported in Safari browsers.

More info: Filters

id

Type undefined | stringInherited from IEntitySettings

A unique ID for looking the element up in root.entitiesById. Setting an ID that another element already has throws an error.

ignoreThemes

Type undefined | false | trueDefault falseInherited from IEntitySettingsSince 5.15.6

Ignores themes: no theme rule applies to the element, not even one of the default theme.

interactive

Type undefined | false | trueInherited from ISpriteSettings

Makes the element respond to the pointer. Adding a pointer event listener to it turns this on.

interactiveChildren

Type undefined | false | trueDefault trueInherited from IContainerSettings

Makes every descendant, not just direct children, interactive when the container itself is interactive.

invert

Type undefined | numberInherited from ISpriteSettingsSince 5.5.0

Color inversion, from 0 (no changes) to 1 (fully inverted colors).

IMPORTANT: This setting is not supported in Safari browsers.

More info: Filters

isMeasured

Type undefined | false | trueDefault trueInherited from ISpriteSettings

If false, the element's bounds are not measured, so it takes no part in its parent's layout or size.

layer

Type undefined | numberInherited from ISpriteSettings

Layer to draw the element on: elements on higher layers show in front of those on lower ones. If not set, the element is on its parent's layer.

layerMargin

Type IMarginInherited from ISpriteSettingsSince @5.2.39

Margins in pixels that make the element's layer larger than the chart, or, when negative, smaller.

layout

Type Layout | nullInherited from IContainerSettings

How children are arranged, e.g. root.horizontalLayout, root.verticalLayout or root.gridLayout. Without a layout, children are placed by their own x and y.

More info: Containers: layout

marginBottom

Type undefined | numberInherited from ISpriteSettings

Bottom margin in pixels.

marginLeft

Type undefined | numberInherited from ISpriteSettings

Left margin in pixels.

marginRight

Type undefined | numberInherited from ISpriteSettings

Right margin in pixels.

marginTop

Type undefined | numberInherited from ISpriteSettings

Top margin in pixels.

mask

Type Graphics | nullInherited from IContainerSettings

An element whose shape clips the container's children.

More info: Containers: masks

maskContent

Type undefined | false | trueInherited from IContainerSettings

Clips all content that goes outside the container's bounds.

maxHeight

Type number | nullInherited from ISpriteSettings

Maximum allowed height in pixels.

maxWidth

Type number | nullInherited from ISpriteSettings

Maximum allowed width in pixels.

minHeight

Type number | nullInherited from ISpriteSettings

Minimum allowed height in pixels.

minWidth

Type number | nullInherited from ISpriteSettings

Minimum allowed width in pixels.

numberFormatter

Type NumberFormatter | undefinedInherited from ISpriteSettings

A NumberFormatter to use for this element instead of the root's.

More info: /v5/concepts/using-formatters/

opacity

Type undefined | numberDefault 1Inherited from ISpriteSettings

Opacity, from 0 (transparent) to 1 (opaque).

The theme's "default" state has opacity: 1, so show(), and leaving a state that changes opacity, bring it back to 1, not to a value set here. To come back to another value, set it in the "default" state too:

sprite.states.create("default", { opacity: 0.5 }).

paddingBottom

Type undefined | numberInherited from IContainerSettings

Bottom padding in pixels.

paddingLeft

Type undefined | numberInherited from IContainerSettings

Left padding in pixels.

paddingRight

Type undefined | numberInherited from IContainerSettings

Right padding in pixels.

paddingTop

Type undefined | numberInherited from IContainerSettings

Top padding in pixels.

patterns

Type PatternSetInherited from ISerialChartSettingsSince 5.10.0

The PatternSet series take their patterns from.

More info: Patterns: pattern sets

position

Type "absolute" | "relative"Default "relative"Inherited from ISpriteSettings

Positioning of the element.

"absolute" leaves the element out of its parent's layout and size: it is placed by its x and y only.

reverseChildren

Type undefined | false | trueInherited from IContainerSettingsSince 5.1.1

Lays out the children in reverse order.

role

Type RoleInherited from ISpriteSettings

Element's role.

More info: Accessibility: roles

rotation

Type undefined | numberDefault 0Inherited from ISpriteSettings

Rotation in degrees, clockwise, around the point set by centerX and centerY.

saturate

Type undefined | numberInherited from ISpriteSettingsSince 5.5.0

Saturation.

  • 0 - grayscale

  • 1 - no changes (default)

  • >1 - more saturated IMPORTANT: This setting is not supported in Safari browsers.

More info: Filters

scale

Type undefined | numberDefault 1Inherited from ISpriteSettings

Scale, around the point set by centerX and centerY: below 1 shrinks the element, above 1 enlarges it.

sepia

Type undefined | numberInherited from ISpriteSettingsSince 5.5.0

Sepia tone, from 0 (no changes) to 1 (full sepia).

IMPORTANT: This setting is not supported in Safari browsers.

More info: Filters

setStateOnChildren

Type undefined | false | trueDefault falseInherited from IContainerSettings

Applies every state set on the container to its children too.

More info: Containers: states

showTooltipOn

Type "hover" | "always" | "click"Default "hover"Inherited from ISpriteSettingsSince 5.0.16

When the element's tooltip shows:

  • "hover" (default) - while the pointer is over the element, or after a tap on it until a tap elsewhere.

  • "always" - all the time. To show tooltips of several elements at once, give each its own Tooltip (tooltip).

  • "click" - after a click or tap on the element, until a click anywhere else on the page.

More info: Tooltips: sticky tooltips

stateAnimationDuration

Type undefined | numberDefault 0Inherited from IEntitySettings

How long, in milliseconds, a switch from one state to another animates.

0 switches at once.

stateAnimationEasing

Type $ease.EasingDefault out(cubic)Inherited from IEntitySettings

Easing of the animated switch from one state to another.

tabindexOrder

Type undefined | numberInherited from ISpriteSettings

An internal order by which focusable elements will be selected within the chart.

More info: Accessibility: focusing elements

templateField

Type undefined | stringInherited from ISpriteSettings

Field in the data item's data object that holds settings for this element, applied over its template's.

More info: Template fields

themes

Type ArrayInherited from IEntitySettings

Themes applied to the element and everything inside it.

themeTags

Type ArrayInherited from IEntitySettings

Tags that theme rules can target. They also count for the element's children, so a rule can match a child by a tag of its parent.

More info: Themes

themeTagsSelf

Type ArrayInherited from IEntitySettings

Tags that theme rules can target, like themeTags, but only for this element, not its children.

More info: Themes

toggleKey

Type "disabled" | "active" | "none" | undefinedInherited from ISpriteSettings

Setting that a click or tap toggles between true and false:

"active" or "disabled". "none" turns toggling off.

tooltip

Type TooltipInherited from ISpriteSettings

The Tooltip to show for the element. If not set, the nearest parent's is used.

tooltipHTML

Type undefined | stringInherited from ISpriteSettingsSince 5.2.11

HTML content of the element's tooltip, shown in place of tooltipText.

tooltipPosition

Type "fixed" | "pointer"Default "fixed"Inherited from ISpriteSettings

Where the tooltip points: "fixed" at tooltipX and tooltipY, or "pointer" at the pointer, following it.

tooltipText

Type undefined | stringInherited from ISpriteSettings

Text of the element's tooltip. It can hold data placeholders, such as {value}.

tooltipX

Type number | PercentDefault am5.percent(50)Inherited from ISpriteSettings

Where on the element the tooltip points, horizontally: pixels from its left edge, or a percent of its width.

tooltipY

Type number | PercentDefault am5.percent(50)Inherited from ISpriteSettings

Where on the element the tooltip points, vertically: pixels from its top edge, or a percent of its height.

userData

Type anyInherited from IEntitySettings

Any data of your own to keep with the element.

verticalScrollbar

Type ScrollbarInherited from IContainerSettings

A Scrollbar that scrolls the content vertically when it does not fit in the container.

More info: Containers: scrollbar

visible

Type undefined | false | trueDefault trueInherited from ISpriteSettings

Whether the element is shown. Unlike show() and hide(), it does not animate.

wheelable

Type undefined | false | trueInherited from ISpriteSettings

Makes the element receive mouse wheel events. While the pointer is over it, the wheel no longer scrolls the page.

width

Type number | Percent | nullInherited from ISpriteSettings

Width in pixels, or a Percent of the parent's inner width. In a horizontal layout, a percent width is a share of the width the other children leave.

x

Type number | Percent | nullInherited from ISpriteSettings

X position in the parent: pixels from its left edge, or a Percent of its inner width, measured from inside its left padding.

y

Type number | Percent | nullInherited from ISpriteSettings

Y position in the parent: pixels from its top edge, or a Percent of its inner height, measured from inside its top padding.