Skip to content
amCharts 5

Utils

Type module

Sources

Items from Utils can be imported/included and used via following ways.

/**
 * Import via main package
 * Access items like: am5.utils.myVariable
 */
import * as am5 from "@amcharts/amcharts5";


/**
 * Import via: Utils.ts
 * Access items like: $utils.myVariable
 */
import * as $utils from "@amcharts/amcharts5/Utils";

Variables

Utils does not have any variables.

Functions

addSpacing(str: string)

Returns string

Adds a space before each uppercase letter, except the first character.

Characters without case, such as digits and spaces, count as uppercase.

alternativeColor(color: iRGB,
lightAlternative: iRGB,
darkAlternative: iRGB)

Returns iRGB

Returns lightAlternative or darkAlternative, whichever contrasts more with color.

brighten(rgb: $type.Optional,
percent: number)

Returns $type.Optional

Returns a color brightened by percent, from -1 to 1. Unlike lighten(), it adds the same amount to every channel.

capitalizeFirst(text: string)

Returns string

Capitalizes the first letter of a string.

contains(a: Element,
b: Element)

Returns boolean

Checks if element a contains element b, or is b. Looks across shadow DOM boundaries too.

escapeForRgex(value: string)

Returns string

Escapes string so it can safely be used in a Regex.

get12Hours(hours: number,
base?: undefined | number)

Returns number

Returns 12-hour representation out of the 24-hour hours.

getDayFromWeek(week: number,
year: number,
weekday: number,
utc: boolean)

Returns number

Returns a year day out of the given week number.

getEventTarget(event: Event | Touch)

Returns Node | null

Gets the target of the event, works for shadow DOM too.

getLightnessStep(value: number,
percent: number)

Returns number

Gets lightness step.

getMonthWeek(date: Date,
utc: boolean)

Returns number

Returns a week number in the month.

getSafeResolution()

Returns number | undefined

Returns a safe canvas resolution for the current device.

Returns 1 on iOS to avoid memory issues, undefined otherwise.

getShadowRoot(a: Node)

Returns ShadowRoot | null

Returns the shadow root the node is in, or null if it is not in one.

getTimeZone(date: Date,
long: boolean,
savings: boolean,
utc: boolean,
timezone?: undefined | string)

Returns string

Returns a string name of the time zone.

getTimezoneOffset(timezone: string,
targetDate?: Date)

Returns number

Returns the UTC offset in minutes for a given timezone, positive west of UTC, as with Date.getTimezoneOffset().

getWeek(date: Date,
utc: boolean)

Returns number

Returns the ISO 8601 week number of a date: weeks start on Monday, and week 1 is the one with the year's first Thursday.

getWeekYear(date: Date,
utc: boolean)

Returns numberSince 5.3.0

Returns the year that the ISO 8601 week of the date belongs to. Around January 1 it can differ from the calendar year.

getYearDay(date: Date,
utc: boolean)

Returns number

Returns the day of the year, 1 being January 1.

hslToHsv(hsl: iHSL)

Returns iHSV

Converts HSL to HSV.

https://en.wikipedia.org/wiki/HSL_and_HSV#HSL_to_HSV

hslToRgb(color: iHSL)

Returns iRGB

Converts an HSL color to RGB: h, s and l from 0 to 1 in, r, g and b from 0 to 255 out. Alpha is not carried over.

Function adapted from:

http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c

hsvToHsl(hsv: iHSV)

Returns iHSL

Converts HSV to HSL.

https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_HSL

iOS()

Returns boolean

Returns true if the current device is running iOS.

isLight(color: iRGB)

Returns boolean

Returns true if color is "light", for example to pick dark text to go on it.

isLocalEvent(event: IPointerEvent,
target: Sprite)

Returns booleanSince 5.2.8

Returns true if pointer event originated on an element within Root.

isTouchEvent(ev: MouseEvent | Touch)

Returns boolean

Returns true if the event came from touch or a pen, false if from a mouse.

lighten(rgb: $type.Optional,
percent: number)

Returns $type.Optional

Returns a color lightened by percent, from -1 to 1: 0.2 moves each channel 20% of the way to 255. A negative value darkens it toward 0.

onZoom(listener: () => void)

Returns IDisposer

Calls listener when the window is resized, which also happens when the browser's zoom changes.

padString(value: any,
len: number,
char: string)

Returns string

Pads a string with additional characters to certain length.

plainText(text: string)

Returns string

Replaces line breaks in a string with ". " and removes HTML tags.

ready(f: () => void)

Returns voidSince 5.0.2

Calls f when the DOM is ready, or right away if it already is.

relativeToValue(percent: number | Percent | undefined | null,
full: number)

Returns number

Converts a value that can be a number or Percent to an absolute number relative to the given full value.

removeElement(el: HTMLElement)

Returns void

Removes a DOM element.

rgbToHsl(color: iRGB)

Returns iHSL

Converts an RGB color to HSL: r, g and b from 0 to 255 in, h, s and l from 0 to 1 out. Alpha is not carried over.

Function adapted from:

http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c

sanitizeHTML(html: string)

Returns stringSince 5.19.0

Removes the parts of an HTML string that are practically only used for cross-site scripting (XSS), leaving legitimate markup intact:

  • <script>, <iframe>, <object>, <embed> and similar dangerous tags;

  • inline event handler attributes (onerror, onload, onclick, ...);

  • javascript: / vbscript: (and similar) protocol URLs in attributes;

  • inline styles that smuggle in scripts via expression(), url(javascript:...), behavior, or -moz-binding.

Root applies it to the HTML it puts on the page (html and labelHTML settings, HTML tooltips, modals, export menu labels), unless its sanitizeHTML setting is false.

saturate(rgb: $type.Optional,
saturation: number)

Returns $type.Optional

Returns rgb with its saturation set to saturation, from 0 (grey) to 1. The value replaces the color's saturation; 1 returns rgb unchanged.

setInteractive(target: HTMLElement,
interactive: boolean)

Returns void

Disables or enables interactivity of a DOM element.

splitString(source: string)

Returns string[]

Splits the string into separate characters. Keeps RTL words non-split.

stripFormatTags(text: string)

Returns string

Strips inline formatting tags (square brackets) from the string.

stripTags(text: string)

Returns string

Strips all tags from the string.

trim(text: string)

Returns string

Removes whitespace from both ends of a string.

trimLeft(text: string)

Returns string

Removes whitespace from the beginning of a string.

trimRight(text: string)

Returns string

Removes whitespace from the end of a string.

truncateTextWithEllipsis(text: string,
maxLength: number,
breakWords: boolean,
ellipsis: string)

Returns string

Truncates a string to a maximum length, appending an ellipsis.