Sprite - amCharts 5

A base class for all visual elements.

Overview

Sprite is the foundational building block for all visual elements in amCharts 5. It provides common functionality for positioning, styling, events, states, and accessibility.

Creating a Sprite

Sprite is an abstract class and cannot be instantiated directly. Use specific sprite types like Rectangle, Graphics, or Container instead.

Properties

Position and Dimensions

number | Percent

X position relative to parent

number | Percent

Y position relative to parent

width

number | Percent

Element’s absolute width in pixels (numeric) or relative width to parent (Percent)

height

number | Percent

Element’s absolute height in pixels (numeric) or relative height to parent (Percent)

maxWidth

number

Maximum allowed width in pixels

maxHeight

number

Maximum allowed height in pixels

minWidth

number

Minimum allowed width in pixels

minHeight

number

Minimum allowed height in pixels

number

default:0

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

number

default:0

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

Visual Appearance

opacity

number

default:1

Opacity. 0 - fully transparent; 1 - fully opaque.

rotation

number

default:0

Rotation in degrees

scale

number

default:1

Scale. Setting to a value less than 1 will shrink object.

visible

boolean

default:true

Is element visible?

forceHidden

boolean

If set to true the element will be hidden regardless of visible or even if show() is called

Positioning

centerX

number | Percent

X coordinate of the center of the element relative to itself. Center coordinates will affect placement as well as rotation pivot point.

centerY

number | Percent

Y coordinate of the center of the element relative to itself. Center coordinates will affect placement as well as rotation pivot point.

position

'absolute' | 'relative'

Positioning of the element. “absolute” means element will not participate in parent layout scheme.

Margins

marginLeft

number

default:0

Left margin in pixels

marginRight

number

default:0

Right margin in pixels

marginTop

number

default:0

Top margin in pixels

marginBottom

number

default:0

Bottom margin in pixels

Interactivity

interactive

boolean

Should this element accept user interaction events?

draggable

boolean

If set to true, user will be able to drag this element. It will also disable default drag events over the area of this element.

wheelable

boolean

If set to true, mouse wheel events will be triggered over the element. It will also disable page scrolling using mouse wheel when pointer is over the element.

forceInactive

boolean

If set to true the element will be inactive - absolutely oblivious to all interactions

Tooltips

Tooltip instance

Text to show in a tooltip when hovered

HTML content to show in a tooltip when hovered

Tooltip pointer X coordinate relative to the element itself

Tooltip pointer Y coordinate relative to the element itself

Tooltip position

Defines when tooltip is shown over the element

See Sticky tooltips for more info.

Visual Effects

filter

string

An SVG filter to apply to the element. IMPORTANT: SVG filters are not supported in some browsers, e.g. Safari.

blur

number

Apply blur filter. Ranges from 0 to X pixels. IMPORTANT: Not supported in Safari.

brightness

number

Modify visual brightness. Range: 0 to 1. IMPORTANT: Not supported in Safari.

contrast

number

Modify contrast. Range: 0 to 1. IMPORTANT: Not supported in Safari.

saturate

number

Modify saturation. 0 = grayscale, 1 = no changes, >1 = more saturated. IMPORTANT: Not supported in Safari.

sepia

number

Apply sepia filter. Range: 0 (no changes) to 1 (complete sepia). IMPORTANT: Not supported in Safari.

invert

number

Invert colors. Range: 0 (no changes) to 1 (completely inverted). IMPORTANT: Not supported in Safari.

hue

number

Rotate HUE colors in degrees. Range: 0 to 360. IMPORTANT: Not supported in Safari.

See Filters for more info.

Appearance

cursorOverStyle

string

A named mouse cursor style to show when hovering this element

See cursor for more info.

crisp

boolean

default:false

If set to true, element will try to draw itself crisp on screen with minimal anti-aliasing

Layer

layer

number

Numeric layer to put element in. Elements with higher number will appear in front of ones with lower number.

layerMargin

IMargin

Margins for the layer. Can be used to make the layer larger or smaller than default chart size.

States

active

boolean

Indicates if element is currently active

disabled

boolean

Indicates if element is disabled

toggleKey

'disabled' | 'active' | 'none'

If set, element will toggle specified boolean setting between true and false when clicked/touched

Data

templateField

string

Allows binding element’s settings to data

See Template fields for more info.

Export

exportable

boolean

If set to false this element will not appear in exported snapshots of the chart

Layout

isMeasured

boolean

If set to false element will not be measured and cannot participate in layout schemes

Formatters

numberFormatter

NumberFormatter

An instance of NumberFormatter that should be used instead of global formatter object

dateFormatter

DateFormatter

An instance of DateFormatter that should be used instead of global formatter object

durationFormatter

DurationFormatter

An instance of DurationFormatter that should be used instead of global formatter object

See Using formatters for more info.

Accessibility

focusable

boolean

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

tabindexOrder

number

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

focusableGroup

string | number

An identifier by which to group common elements into focusable groups

See Grouping focusable elements for more info.

hoverOnFocus

boolean

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

clickAnnounceText

string

If set, the text will be read out (announced) by a screen reader when focused element is “clicked”

role

Role

Element’s role

See Roles for more info.

ariaLabel

string

Label for the element to use for screen readers

ariaLive

AriaLive

aria-live setting

ariaChecked

boolean

aria-checked setting

ariaCurrent

string

aria-current setting

ariaSelected

boolean

aria-selected setting

ariaHidden

boolean

aria-hidden setting

ariaOrientation

string

aria-orientation setting

ariaValueNow

string

aria-valuenow setting

ariaValueMin

string

aria-valuemin setting

ariaValueMax

string

aria-valuemax setting

ariaValueText

string

aria-valuetext setting

ariaControls

string

aria-controls setting

See Screen reader for more info.

Methods

show()

Shows currently hidden element.

duration

number

Animation duration in milliseconds

promise

Promise<void>

Promise that resolves when animation completes

await sprite.show(500);

hide()

Hides currently visible element.

duration

number

Animation duration in milliseconds

promise

Promise<void>

Promise that resolves when animation completes

await sprite.hide(500);

isHidden()

Returns true if element is currently hidden.

hidden

boolean

Whether element is hidden

isVisibleDeep()

Returns true if element and all its parents are visible.

visible

boolean

Whether element is visible

showTooltip()

Shows element’s Tooltip.

point

IPoint

Optional point coordinates

promise

Promise<void> | undefined

Promise that resolves when tooltip is shown

sprite.showTooltip();

hideTooltip()

Hides element’s Tooltip.

promise

Promise<void> | undefined

Promise that resolves when tooltip is hidden

sprite.hideTooltip();

getTooltip()

Returns Tooltip used for this element.

Tooltip instance

const tooltip = sprite.getTooltip();

hover()

Simulate hover over element.

sprite.hover();

unhover()

Simulate unhover over element.

sprite.unhover();

isHover()

Returns true if element is currently hovered.

hovered

boolean

Whether element is hovered

dragStart()

Initiates drag operation.

event

ISpritePointerEvent

required

Pointer event

dragStop()

Stops drag operation.

event

ISpritePointerEvent

required

Pointer event

dragMove()

Handles drag move.

event

ISpritePointerEvent

required

Pointer event

isDragging()

Returns true if element is currently being dragged.

dragging

boolean

Whether element is being dragged

x()

Returns element’s actual X position in pixels.

number

X position in pixels

const x = sprite.x();

y()

Returns element’s actual Y position in pixels.

number

Y position in pixels

const y = sprite.y();

width()

Returns element’s width in pixels.

width

number

Width in pixels

const width = sprite.width();

height()

Returns element’s height in pixels.

height

number

Height in pixels

const height = sprite.height();

globalBounds()

Returns global coordinates of the element’s bounds.

bounds

IBounds

Bounds object with left, right, top, bottom properties

const bounds = sprite.globalBounds();
console.log(bounds.left, bounds.top, bounds.right, bounds.bottom);

localBounds()

Returns local coordinates of the element’s bounds.

bounds

IBounds

Bounds object with left, right, top, bottom properties

depth()

Returns depth (how deep in the hierarchy of the content tree) of this element.

depth

number

Depth level

const depth = sprite.depth();

toGlobal()

Converts local coordinates to global.

point

IPoint

required

Local point

point

IPoint

Global point

const globalPoint = sprite.toGlobal({ x: 10, y: 20 });

toLocal()

Converts global coordinates to local.

point

IPoint

required

Global point

point

IPoint

Local point

const localPoint = sprite.toLocal({ x: 100, y: 200 });

markDirty()

Marks element as dirty, triggering re-render.

sprite.markDirty();

markDirtyBounds()

Marks element’s bounds as dirty.

sprite.markDirtyBounds();

markDirtyPosition()

Marks element’s position as dirty.

sprite.markDirtyPosition();

markDirtyAccessibility()

Marks element’s accessibility settings as dirty.

sprite.markDirtyAccessibility();

Events

click

ISpritePointerEvent

Invoked when element is clicked or tapped

rightclick

ISpritePointerEvent

Invoked when element is clicked with the right mouse button

middleclick

ISpritePointerEvent

Invoked when element is clicked with the middle mouse button

dblclick

ISpritePointerEvent

Invoked when element is double-clicked or tapped twice quickly

pointerover

ISpritePointerEvent

Invoked when pointer moves over the element

pointerout

ISpritePointerEvent

Invoked when pointer moves outside the element

pointerdown

ISpritePointerEvent

Invoked when pointer button is pressed or touch starts over the element

pointerup

ISpritePointerEvent

Invoked when pointer button is released or touch stops over the element

globalpointerup

ISpritePointerEvent

Invoked when pointer button is released anywhere in the window

globalpointermove

ISpritePointerEvent

Invoked when pointer is moving anywhere in the window

dragstart

ISpritePointerEvent

Invoked when element dragging starts

dragstop

ISpritePointerEvent

Invoked when element dragging stops

dragged

ISpritePointerEvent

Invoked when element is being dragged

wheel

{ originalEvent: WheelEvent; point: IPoint }

Invoked when mouse wheel is spinned while pointer is over the element

focus

{ originalEvent: FocusEvent; target: Sprite }

Invoked when element gains focus

blur

{ originalEvent: FocusEvent; target: Sprite }

Invoked when element loses focus

positionchanged

{}

Invoked when element’s position (X/Y) changes

boundschanged

{}

Invoked when element’s bounds change due to any manipulation to it

dataitemchanged

{ oldDataItem: DataItem | undefined, newDataItem: DataItem | undefined }

Invoked when element’s data item changes

sprite.events.on("click", (ev) => {
  console.log("Sprite clicked at:", ev.point);
});

sprite.events.on("dragstart", (ev) => {
  console.log("Drag started");
});

Core

Shapes

Controls

XY Charts

Map Charts

Stock Charts

Hierarchy Charts

Utilities

​Overview

​Creating a Sprite

​Properties

​Position and Dimensions

​Visual Appearance

​Positioning

​Margins

​Interactivity

​Tooltips

​Visual Effects

​Appearance

​Layer

​States

​Data

​Export

​Layout

​Formatters

​Accessibility

​Methods

​show()

​hide()

​isHidden()

​isVisibleDeep()

​showTooltip()

​hideTooltip()

​getTooltip()

​hover()

​unhover()

​isHover()

​dragStart()

​dragStop()

​dragMove()

​isDragging()

​x()

​y()

​width()

​height()

​globalBounds()

​localBounds()

​depth()

​toGlobal()

​toLocal()

​markDirty()

​markDirtyBounds()

​markDirtyPosition()

​markDirtyAccessibility()

​Events

Build docs developers (and LLMs) love

Overview

Creating a Sprite

Properties

Position and Dimensions

Visual Appearance

Positioning

Margins

Interactivity

Tooltips

Visual Effects

Appearance

Layer

States

Data

Export

Layout

Formatters

Accessibility

Methods

show()

hide()

isHidden()

isVisibleDeep()

showTooltip()

hideTooltip()

getTooltip()

hover()

unhover()

isHover()

dragStart()

dragStop()

dragMove()

isDragging()

x()

y()

width()

height()

globalBounds()

localBounds()

depth()

toGlobal()

toLocal()

markDirty()

markDirtyBounds()

markDirtyPosition()

markDirtyAccessibility()

Events