Sprite – amCharts 5 Documentation

Type class

A base class for all visual elements.

Sources

Sprite can be used (imported) via one of the following packages.

// Sprite is available in all of the following modules.
// You only need to import one of them.

/**
 * --------------------------------------------------------
 * Import from: "index.ts"
 * Use like: am5.Sprite
 * --------------------------------------------------------
 */
import * as am5 from "@amcharts/amcharts5";

// Sprite is available in all of the following modules.
// You only need to import one of them.

/**
 * --------------------------------------------------------
 * Include via: <script src="index.js"></script>
 * Access items like: am5.Sprite
 * --------------------------------------------------------
 */

Inheritance

Sprite extends Entity.

Sprite is extended by Graphics, Container, Picture.

Settings

Set these settings on a Sprite object using its set() and setAll() methods.

Read about settings concept.

active #	Type `undefined` \| `false` \| `true` Indicates if element is currently active.
centerX #	Type `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 #	Type `number` \| `Percent` Y coordinate of the center of the element relative to itself. Center coordinates will affect placement as well as rotation pivot point.
cursorOverStyle #	Type `undefined` \| `string` A named mouse cursor style to show when hovering this element. Click here for more info
dateFormatter #	Type `DateFormatter` \| `undefined` An instance of `DateFormatter` that should be used instead of global formatter object. Click here for more info
disabled #	Type `undefined` \| `false` \| `true` Indicates if element is disabled.
draggable #	Type `undefined` \| `false` \| `true` 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.
durationFormatter #	Type `DurationFormatter` \| `undefined` An instance of `DurationFormatter` that should be used instead of global formatter object. Click here for more info
dx #	Type `undefined` \| `number` Horizontal shift in pixels. Can be negative to shift leftward.
dy #	Type `undefined` \| `number` Vertical shift in pixels. Can be negative to shift upward.
exportable #	Type `undefined` \| `false` \| `true` If set to `false` this element will not appear in exported snapshots of the chart.
forceHidden #	Type `undefined` \| `false` \| `true` If set to `true` the element will be hidden regardless of `visible` or even if `show()` is called.
forceInactive #	Type `undefined` \| `false` \| `true` If set to `true` the element will be inactive - absolutely oblivious to all interactions, even if there are related events set, or the `interactive: true` is set. @since 5.0.21
height #	Type `number` \| `Percent` \| `null` Element's absolute height in pixels (numeric value) or relative height to parent (`Percent`);
id #	Type `undefined` \| `string` Inherited from `IEntitySettings` A custom string ID for the element. If set, element can be looked up via `am5.registry.entitiesById`. Will raise error if an element with the same ID already exists.
interactive #	Type `undefined` \| `false` \| `true` Should this element accept user interaction events?
isMeasured #	Type `undefined` \| `false` \| `true` If set to `false` element will not be measured and cannot participate in layout schemes.
layer #	Type `undefined` \| `number` Numeric layer to put element in. Elements with higher number will appear in front of the ones with lower numer. If not set, will inherit layer from its ascendants.
marginBottom #	Type `undefined` \| `number` Bottom margin in pixels.
marginLeft #	Type `undefined` \| `number` Left margin in pixels.
marginRight #	Type `undefined` \| `number` Right margin in pixels.
marginTop #	Type `undefined` \| `number` Top margin in pixels.
maxHeight #	Type `number` \| `null` Maximum allowed height in pixels.
maxWidth #	Type `number` \| `null` Maximum allowed width in pixels.
minHeight #	Type `number` \| `null` Minimum allowed height in pixels.
minWidth #	Type `number` \| `null` Minimum allowed width in pixels.
numberFormatter #	Type `NumberFormatter` \| `undefined` An instance of `NumberFormatter` that should be used instead of global formatter object. Click here for more info
opacity #	Type `undefined` \| `number` Opacity. 0 - fully transparent; 1 - fully opaque.
position #	Type `"absolute"` \| `"relative"` Positioning of the element. `"absolute"` means element will not participate in parent layout scheme, and will be positioned solely accoridng its `x` and `y` settings.
rotation #	Type `undefined` \| `number` Rotation in degrees.
scale #	Type `undefined` \| `number` Scale. Setting to a value less than 1 will shrink object.
showTooltipOn #	Type `"hover"` \| `"always"` Default `"hover"` Defines when tooltip is shown over the element. Available options: `"hover"` (default) - tooltip is shown when element is hovered by a pointer or touched. It is hidden as soon as element is not hovered anymore, or touch occurs outside it. `"always"` - a tooltip will always be shown over the element, without any interactions. Please note that if you need to show tooltips for multiple elements at the same time, you need to explicitly create a `Tooltip` instance and set element's `tooltip` setting with it. Click here for more info @since 5.0.16
stateAnimationDuration #	Type `undefined` \| `number` Inherited from `IEntitySettings` Duration of transition from one state to another.
stateAnimationEasing #	Type `$ease.Easing` Inherited from `IEntitySettings` Easing of transition from one state to another.
templateField #	Type `undefined` \| `string` Allows binding element's settings to data. Click here for more info
themeTags #	Type `Array` Inherited from `IEntitySettings` Tags which can be used by the theme rules. Click here for more info
themeTagsSelf #	Type `Array` Inherited from `IEntitySettings` Tags which can be used by the theme rules. These tags only apply to this object, not any children. Click here for more info
themes #	Type `Array` Inherited from `IEntitySettings` A list of themes applied to the element.
toggleKey #	Type `"disabled"` \| `"active"` \| `"none"` \| `undefined` If set, element will toggle specified boolean setting between `true` and `false` when clicked/touched.
tooltip #	Type `Tooltip` `Tooltip` instance.
tooltipPosition #	Type `"fixed"` \| `"pointer"` Tooltip position.
tooltipText #	Type `undefined` \| `string` Text to show in a tooltip when hovered.
tooltipX #	Type `number` \| `Percent` Tooltip pointer X coordinate relative to the element itself.
tooltipY #	Type `number` \| `Percent` Tooltip pointer Y coordinate relative to the element itself.
userData #	Type `any` Inherited from `IEntitySettings` A storage for any custom user data that needs to be associated with the element.
visible #	Type `undefined` \| `false` \| `true` Is element visible?
wheelable #	Type `undefined` \| `false` \| `true` 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.
width #	Type `number` \| `Percent` \| `null` Element's absolute width in pixels (numeric value) or relative width to parent (`Percent`);
x #	Type `number` \| `Percent` \| `null` X position relative to parent.
y #	Type `number` \| `Percent` \| `null` Y position relative to parent.
There are 7 inherited items currently hidden from this list.

Private settings

These are read-only settings accessible from a Sprite object using its getPrivate() method.

Read about private settings.

showingTooltip #	Read only Type `undefined` \| `false` \| `true` Is element currently showing a tooltip?
tooltipTarget #	Read only Type `Graphics` An element tooltip should inherit its colors from.

showingTooltip
#

Read only

Type undefined | false | true

Is element currently showing a tooltip?

tooltipTarget
#

Read only

Type Graphics

An element tooltip should inherit its colors from.

Properties

adapters #	Type `Adapters` Default `new Adapters(this)` Inherited from `Entity`
className #	Static Type `string` Default `"Sprite"`
classNames #	Static Type `Array` Default `"Sprite", "Entity"`
dataItem #	Type `DataItem` \| `undefined` A `DataItem` used for this element. NOTE: data item is being assigned automatically in most cases where it matters. Use this accessor to set data item only if you know what you're doing.
events #	Type `SpriteEventDispatcher`
parent #	Type `Container` \| `undefined` Parent `Container` of this element.
root #	Type `Root` Inherited from `Entity` An instance of `Root` object. @readonly @since 5.0.6
states #	Type `States` Default `new States(this)` Inherited from `Entity`
template #	Type `Template` \| `undefined` Inherited from `Entity` @todo needs description
uid #	Type `number` Default `++counter` Inherited from `Settings` Unique ID.
There are 5 inherited items currently hidden from this list.

Methods

animate( options: `AnimationOptions` ) #	Returns `Animation` Inherited from `Settings` Animates setting values from current/start values to new ones. Click here for more info
appear( duration?: `undefined` \| `number`, delay?: `undefined` \| `number` ) #	Returns `Promise` Plays initial reveal animation regardless if element is currently hidden or visible.
depth() #	Returns `number` Returns depth (how deep in the hierachy of the content tree) of this element.
dispose() #	Returns `void` Inherited from `Settings` Disposes this object.
get( key: `Key`, fallback: `F` ) #	Returns `NonNullable` \| `F` Inherited from `Entity` Returns settings value for the specified `key`. If there is no value, `fallback` is returned instead (if set). Click here for more info
getDateFormatter() #	Returns `DateFormatter` Returns an instance of `DateFormatter` used in this element. If this element does not have it set, global one form `Root` is used. Click here for more info
getDurationFormatter() #	Returns `DurationFormatter` Returns an instance of `DurationFormatter` used in this element. If this element does not have it set, global one form `Root` is used. Click here for more info
getNumberFormatter() #	Returns `NumberFormatter` Returns an instance of `NumberFormatter` used in this element. If this element does not have it set, global one form `Root` is used. Click here for more info
getTooltip() #	Returns `Tooltip` \| `undefined` Returns `Tooltip` used for this element.
height() #	Returns `number` Returns height of this element in pixels.
hide( duration?: `undefined` \| `number` ) #	Returns `Promise` Hides the element and returns a `Promise` which completes when all hiding animations are finished. series.hide().then(function(ev) { console.log("Series finished hiding"); }) series.hide().then(function(ev) { console.log("Series finished hiding"); })
hideTooltip() #	Returns `void` Hides element's `Tooltip`.
hover() #	Returns `void` Simulate hover over element.
isDisposed() #	Returns `boolean` Inherited from `Settings` Returns `true` if this element is disposed.
isDragging() #	Returns `boolean` Returns `true` if this element is currently being dragged.
isFocus() #	Returns `boolean` Returns `true` if this element does currently have focus.
isHidden() #	Returns `boolean` Returns `true` if this element is currently hidden.
isHiding() #	Returns `boolean` Returns `true` if this element is currently animating to a hidden state.
isHover() #	Returns `boolean` Returns `true` if this element is currently hovered by a pointer.
isShowing() #	Returns `boolean` Returns `true` if this element is currently animating to a default state.
isType( type: `string` ) #	Returns `this` Inherited from `Entity` Checks if element is of certain class (or inherits one).
maxHeight() #	Returns `number` Returns maximum allowed height of this element in pixels.
maxWidth() #	Returns `number` Returns maximum allowed width of this element in pixels.
new( root: `Root`, settings: `ITSettings`, template?: `Template` ) #	Static Returns `T` Inherited from `Entity` Use this method to create an instance of this class. Click here for more info
on( key: `Key`, callback: ( value: `[""]`, target: `this`, key: `Key`) => `void` ) #	Returns `IDisposer` Inherited from `Settings` Sets a callback function to invoke when specific key of settings changes or is set. Click here for more info
remove( key: `Key` ) #	Returns `void` Inherited from `Entity` Removes a setting value for the specified `key`. Click here for more info
removeAll() #	Returns `void` Inherited from `Settings` Removes all keys; Click here for more info
set( key: `Key`, value: `Value` ) #	Returns `Value` Inherited from `Entity` Sets a setting `value` for the specified `key`, and returns the same `value`. Click here for more info
setAll( settings: `Partial` ) #	Returns `void` Inherited from `Settings` Sets multiple settings at once. `settings` must be an object with key: value pairs. Click here for more info
setTimeout( fn: () => `void`, delay: `number` ) #	Returns `IDisposer` Inherited from `Entity` Creates and returns a "disposable" timeout.
show( duration?: `undefined` \| `number` ) #	Returns `Promise` Shows currently hidden element and returns a `Promise` which completes when all showing animations are finished. series.show().then(function(ev) { console.log("Series is now fully visible"); }) series.show().then(function(ev) { console.log("Series is now fully visible"); })
showTooltip( point?: `IPoint` ) #	Returns `void` Shows element's `Tooltip`.
toBack() #	Returns `void` Moves sprite to the beginning of the parent's children array. Depending on `layout` setting of the parten container, it may effect the positioning or overlapping order of the elements.
toFront() #	Returns `void` Moves sprite to the end of the parent's children array. Depending on `layout` setting of the parten container, it may effect the positioning or overlapping order of the elements.
toGlobal( point: `IPoint` ) #	Returns `IPoint` Converts X/Y coordinate within this element to a global coordinate.
toLocal( point: `IPoint` ) #	Returns `IPoint` Converts global X/Y coordinate to a coordinate within this element.
unhover() #	Returns `void` Simulate unhover over element.
width() #	Returns `number` Returns width of this element in pixels.
x() #	Returns `number` Returns element's actual X position in pixels.
y() #	Returns `number` Returns element's actual Y position in pixels.
There are 12 inherited items currently hidden from this list.

animate(

options: AnimationOptions

)

Returns Animation

Inherited from Settings

Animates setting values from current/start values to new ones.

Click here for more info

appear(

duration?: undefined | number,
delay?: undefined | number

)

Returns Promise

Plays initial reveal animation regardless if element is currently hidden or visible.

depth()

Returns number

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

dispose()

Returns void

Inherited from Settings

Disposes this object.

get(

key: Key,
fallback: F

)

Returns NonNullable | F

Inherited from Entity

Returns settings value for the specified key.

If there is no value, fallback is returned instead (if set).

Click here for more info

getDateFormatter()

Returns DateFormatter

Returns an instance of DateFormatter used in this element.

If this element does not have it set, global one form Root is used.

Click here for more info

getDurationFormatter()

Returns DurationFormatter

Returns an instance of DurationFormatter used in this element.

If this element does not have it set, global one form Root is used.

Click here for more info

getNumberFormatter()

Returns NumberFormatter

Returns an instance of NumberFormatter used in this element.

If this element does not have it set, global one form Root is used.

Click here for more info

getTooltip()

Returns Tooltip | undefined

Returns Tooltip used for this element.

height()

Returns number

Returns height of this element in pixels.

hide(

duration?: undefined | number

)

Returns Promise

Hides the element and returns a Promise which completes when all hiding animations are finished.

series.hide().then(function(ev) {
  console.log("Series finished hiding");
})

series.hide().then(function(ev) {
  console.log("Series finished hiding");
})

hideTooltip()

Returns void

Hides element's Tooltip.

hover()

Returns void

Simulate hover over element.

isDisposed()

Returns boolean

Inherited from Settings

Returns true if this element is disposed.

isDragging()

Returns boolean

Returns true if this element is currently being dragged.

isFocus()

Returns boolean

Returns true if this element does currently have focus.

isHidden()

Returns boolean

Returns true if this element is currently hidden.

isHiding()

Returns boolean

Returns true if this element is currently animating to a hidden state.

isHover()

Returns boolean

Returns true if this element is currently hovered by a pointer.

isShowing()

Returns boolean

Returns true if this element is currently animating to a default state.

isType(

type: string

)

Returns this

Inherited from Entity

Checks if element is of certain class (or inherits one).

maxHeight()

Returns number

Returns maximum allowed height of this element in pixels.

maxWidth()

Returns number

Returns maximum allowed width of this element in pixels.

new(

root: Root,
settings: ITSettings,
template?: Template

)

Static

Returns T

Inherited from Entity

Use this method to create an instance of this class.

Click here for more info

on(

key: Key,
callback: ( value: [""], target: this, key: Key) => void

)

Returns IDisposer

Inherited from Settings

Sets a callback function to invoke when specific key of settings changes or is set.

Click here for more info

remove(

key: Key

)

Returns void

Inherited from Entity

Removes a setting value for the specified key.

Click here for more info

removeAll()

Returns void

Inherited from Settings

Removes all keys;

Click here for more info

set(

key: Key,
value: Value

)

Returns Value

Inherited from Entity

Sets a setting value for the specified key, and returns the same value.

Click here for more info

setAll(

settings: Partial

)

Returns void

Inherited from Settings

Sets multiple settings at once.

settings must be an object with key: value pairs.

Click here for more info

setTimeout(

fn: () => void,
delay: number

)

Returns IDisposer

Inherited from Entity

Creates and returns a "disposable" timeout.

show(

duration?: undefined | number

)

Returns Promise

Shows currently hidden element and returns a Promise which completes when all showing animations are finished.

series.show().then(function(ev) {
  console.log("Series is now fully visible");
})

series.show().then(function(ev) {
  console.log("Series is now fully visible");
})

showTooltip(

point?: IPoint

)

Returns void

Shows element's Tooltip.

toBack()

Returns void

Moves sprite to the beginning of the parent's children array.

Depending on layout setting of the parten container, it may effect the positioning or overlapping order of the elements.

toFront()

Returns void

Moves sprite to the end of the parent's children array.

Depending on layout setting of the parten container, it may effect the positioning or overlapping order of the elements.

toGlobal(

point: IPoint

)

Returns IPoint

Converts X/Y coordinate within this element to a global coordinate.

toLocal(

point: IPoint

)

Returns IPoint

Converts global X/Y coordinate to a coordinate within this element.

unhover()

Returns void

Simulate unhover over element.

width()

Returns number

Returns width of this element in pixels.

x()

Returns number

Returns element's actual X position in pixels.

y()

Returns number

Returns element's actual Y position in pixels.

There are 12 inherited items currently hidden from this list.

Events

Add event handlers to Sprite object using its events.on() method.

Read about adding event handlers.

#blur	Param { originalEvent: `FocusEvent`, target: `Sprite`, type: `"blur"`, target: `this` } Invoked when element loses focus.
#boundschanged	Param { type: `"boundschanged"`, target: `this` } Invoked when element's bounds change due to any manipulation to it.
#click	Param { type: `"click"`, target: `this` } Invoked when element is clicked or tapped.
#dataitemchanged	Param { newDataItem: `DataItem` \| `undefined`, oldDataItem: `DataItem` \| `undefined`, type: `"dataitemchanged"`, target: `this` } Invoked when element's data item changes.
#dblclick	Param { type: `"dblclick"`, target: `this` } Invoked when element is doubleclicked or tapped twice quickly.
#dragged	Param { type: `"dragged"`, target: `this` } Invoked when element ois being dragged.
#dragstart	Param { type: `"dragstart"`, target: `this` } Invoked when element dragging starts.
#dragstop	Param { type: `"dragstop"`, target: `this` } Invoked when element dragging stops.
#focus	Param { originalEvent: `FocusEvent`, target: `Sprite`, type: `"focus"`, target: `this` } Invoked when element gains focus.
#globalpointermove	Param { type: `"globalpointermove"`, target: `this` } Invoked when pointer is moving anywhere in the window, even outside of the element or even chart area.
#globalpointerup	Param { type: `"globalpointerup"`, target: `this` } Invoked when pointer button is released or touch stops in the window, even outside of the element or even chart area.
#middleclick	Param { type: `"middleclick"`, target: `this` } Invoked when element is clicked with the middle mouse button.
#pointerdown	Param { type: `"pointerdown"`, target: `this` } Invoked when pointer button is pressed or touch starts over the element.
#pointerout	Param { type: `"pointerout"`, target: `this` } Invoked when pointer moves outside the element.
#pointerover	Param { type: `"pointerover"`, target: `this` } Invoked when pointer moves over the element.
#pointerup	Param { type: `"pointerup"`, target: `this` } Invoked when pointer button is released or touch stops over the element.
#positionchanged	Param { type: `"positionchanged"`, target: `this` } Invoked when element's position (X/Y) changes.
#rightclick	Param { type: `"rightclick"`, target: `this` } Invoked when element is clicked width the right mouse button.
#wheel	Param { originalEvent: `WheelEvent`, point: `IPoint`, type: `"wheel"`, target: `this` } Invoked when mouse wheel is spinned while pointer is over the element.