Skip to content

JavaScript API

Jump to bottom
thednp edited this page Aug 2, 2022 · 2 revisions

Attributes (src/attr)

getAttribute

Shortie for the HTMLElement.getAttribute() method.

  • Syntax: getAttribute(element, attribute)
  • Kind: global function
  • Returns: string | null
Param Type Description
element HTMLElement target element
attribute string attribute name

getAttributeNS

Shortie for the HTMLElement.getAttributeNS() method.

  • Syntax: getAttributeNS(namespace, element, attribute)
  • Kind: global function
  • Returns: string | null
Param Type Description
namespace string attribute namespace
element HTMLElement target element
attribute string attribute name

hasAttribute

Shortie for the HTMLElement.hasAttribute() method.

  • Kind: global function
  • Syntax: hasAttribute(element, attribute)
  • Returns: boolean
Param Type Description
element HTMLElement target element
attribute string attribute name

hasAttributeNS

Shortie for the HTMLElement.hasAttributeNS() method.

Kind: global function

  • Syntax: hasAttributeNS(namespace, element, attribute)
  • Returns: boolean
Param Type Description
namespace string attribute namespace
element HTMLElement target element
attribute string attribute name

removeAttribute

Shortie for HTMLElement.removeAttribute() method.

  • Kind: global function
  • Syntax: removeAttribute(element, attribute)
  • Returns: void
Param Type Description
element HTMLElement target element
attribute string attribute name

removeAttributeNS

Shortie for HTMLElement.removeAttributeNS() method.

  • Kind: global function
  • Syntax: removeAttributeNS(namespace, element, attribute)
  • Returns: void
Param Type Description
namespace string attribute namespace
element HTMLElement target element
attribute string attribute name

setAttribute

Shortie for HTMLElement.setAttribute() method.

  • Kind: global function
  • Syntax: setAttribute(element, attribute, value)
  • Returns: void
Param Type Description
element HTMLElement target element
attribute string attribute name
value string attribute value

setAttributeNS

Shortie for SVGElement.setAttributeNS() method.

  • Kind: global function
  • Syntax: setAttributeNS(namespace, element, attribute, value)
  • Returns: void
Param Type Description
namespace string attribute namespace
element HTMLElement target element
att string attribute name
value string attribute value

Blocks (src/blocks)

documentBody

A global namespace for document.body or the HTMLBodyElement.

  • Kind: global constant

documentElement

A global namespace for document.documentElement or the HTMLHtmlElement.

  • Kind: global constant

documentHead

A global namespace for document.head or the HTMLHeadElement.

  • Kind: global constant

Boolean (src/boolean)

isApple

A global boolean for Apple browsers.

  • Kind: global constant

isFirefox

A global boolean for Gecko browsers. When writing this file, Gecko was not supporting userAgentData.

  • Kind: global constant

isMobile

A global boolean for mobile detection.

  • Kind: global constant

support3DTransform

A global boolean for CSS3 3D transform support.

  • Kind: global constant

supportAnimation

A global boolean for CSS3 animation support.

  • Kind: global constant

supportPassive

A global boolean for passive events support, in general event options are not suited for scroll prevention.

supportTouch

A global boolean for touch events support.

  • Kind: global constant

supportTransform

A global boolean for CSS3 transform support.

  • Kind: global constant

supportTransition

A global boolean for CSS3 transition support.

  • Kind: global constant

Class (src/class)

addClass

Add class name to HTMLElement.classList.

  • Kind: global function
  • Syntax: addClass(element, 'one') OR addClass(element, 'one', 'two')
  • Returns: void
Param Type Description
element HTMLElement target element
className ...args: Array<string> one or more class names to add

hasClass

Check class in HTMLElement.classList.

  • Kind: global function
  • Syntax: hasClass(element, className)
  • Returns: boolean - the query result
Param Type Description
element HTMLElement target element
className string the className to check

removeClass

Remove class from HTMLElement.classList.

  • Kind: global function
  • Syntax: removeClass(element, className)
  • Returns: void
Param Type Description
element HTMLElement target element
className ...args: Array<string> one or more class names to remove

Event (src/event)

on

Add event listener to an eligible event target.

  • Kind: global function
  • Syntax: on(element, eventName, listener, options)
  • Returns: void
Param Type Description
element EventTarget target element
eventName string the event name
listener EventListener the event listener
options AddEventListenerOptions | boolean | undefined event listener options

off

Remove event listener from event target.

  • Kind: global function
  • Syntax: off(element, eventName, listener, options)
  • Returns: void
Param Type Description
element EventTarget target element
eventName string the event name
listener EventListener the event listener
options AddEventListenerOptions | boolean | undefined event listener options

one

Add an event listener to an eligible target and remove it once the listener is called.

  • Kind: global function
  • Syntax: one(element, eventName, listener, options)
  • Returns: void
Param Type Description
element EventTarget target element
eventName string the event name
listener EventListener the event listener
options AddEventListenerOptions | boolean | undefined event listener options

get (src/get)

getBoundingClientRect

Returns the bounding client rect of a target HTMLElement.

  • Kind: global function
  • Syntax: getBoundingClientRect(element, includeScale)
  • Returns: object containing { width, height, top, right, bottom, left, x, y} properties as numbers
  • See: https://github.com/floating-ui/floating-ui
Param Type Description
element HTMLElement the target element
includeScale boolean | undefined when true, the target scale is also computed

getDocument

Returns the Document or the #document element. When node parameter is provided, it will return the parent document of that particular node.

Param Type Description
node Node | undefined the reference element or node

getDocumentBody

Returns the document.body or the <body> element. When node parameter is provided, it will return the parent <body> of that particular node.

Param Type Description
node Node | undefined the reference node

getDocumentElement

Returns the document.documentElement or the <html> element. When node parameter is provided, it will return the parent <html> of that particular node.

Param Type Description
node Node | undefined the reference node

getDocumentHead

Returns the document.head or the <head> element. When node parameter is provided, it will return the <head> element of the parent Document which contains that particular node.

Param Type Description
node Node | undefined the reference node

getElementAnimationDelay

Utility to get the computed animationDelay from a target element in miliseconds.

  • Kind: global function
  • Syntax: getElementAnimationDelay(element)
  • Returns: number - the delay value in miliseconds
Param Type Description
element HTMLElement the target element

getElementAnimationDuration

Utility to get the computed animationDuration from a target element in miliseconds.

  • Kind: global function
  • Syntax: getElementAnimationDuration(element)
  • Returns: number - the duration value in miliseconds
Param Type Description
element HTMLElement the target element

getElementTransitionDelay

Utility to get the computed transitionDelay from a target element in miliseconds.

  • Kind: global function
  • Syntax: getElementTransitionDelay(element)
  • Returns: number - the delay value in miliseconds
Param Type Description
element HTMLElement the target element

getElementTransitionDuration

Utility to get the computed transitionDuration from a target element in miliseconds.

  • Kind: global function
  • Syntax: getElementTransitionDuration(element)
  • Returns: number - the duration value in miliseconds
Param Type Description
element HTMLElement the target element

getElementStyle

Shortie for window.getComputedStyle(element).propertyName static method. The utility should also work with prefixed properties like "-webkit-transition" and CSS variables --bs-transition via the CSSStyleDeclaration.getPropertyValue() method.

  • Kind: global function
  • Syntax: getElementStyle(element, property)
  • Returns: string - the property value
Param Type Description
element HTMLElement the target element
property string the property name

getNodeScroll

Returns an {x,y} object with the target HTMLElement / Node scroll position.

Param Type Description
element HTMLElement | Window the target element or window

getParentNode

Returns the parentNode of a target element, an utility that also goes through ShadowRoot elements.

Param Type Description
element Node the target element

getRectRelativeToOffsetParent

Returns an element's DOMRect like object relative to a given offset parent and its scroll position.

  • Kind: global function
  • Syntax: getRectRelativeToOffsetParent(element, offsetParent, scroll)
  • Returns: the {x, y, width, height} object representing the size and position of the target element
  • See: https://github.com/floating-ui/floating-ui
Param Type Description
element HTMLElement the target element
offsetParent HTMLElement the offsetParent element
scroll {x: number, y: number} the scroll position of the offsetParent element

getUID

Returns a unique identifier for Popover, Tooltip, ScrollSpy.

Param Type Description
element HTMLElement the target element
key string | undefined the optional identifier key

getWindow

Returns the Window element. When node parameter is provided, it will return the Window instance which contains that particular node.

Param Type Description
node Node the target element or node

is (src/is)

isArray

Shortie for the Array.isArray() static method.

  • Kind: global function
  • Syntax: isArray(array)
  • Returns: boolean - the query result
Param Type Description
obj any | undefined array-like iterable object

isCanvas

Checks if an object is a HTMLCanvas or <canvas> instance.

  • Kind: global function
  • Syntax: isCanvas(element)
  • Returns: boolean - the query result
Param Type Description
obj any | undefined target element

isCustomElement

Checks if an object is a CustomElement instance.

  • Kind: global function
  • Syntax: isCustomElement(element)
  • Returns: boolean - the query result
Param Type Description
element any | undefined the target element

isDocument

Checks if an object is a Document instance.

  • Kind: global function
  • Syntax: isDocument(element)
  • Returns: boolean - the query result
Param Type Description
element any | undefined the target element

isElement

Checks if an object is an Element instance.

  • Kind: global function
  • Syntax: isElement(element)
  • Returns: boolean - the query result
Param Type Description
element any | undefined the target element

isElementInScrollRange

Utility to determine if an HTMLElement is partially visible in viewport.

  • Kind: global function
  • Syntax: isElementInScrollRange(element)
  • Returns: boolean - the query result
Param Type Description
element HTMLElement | undefined target element

isElementInViewport

Utility to determine if an HTMLElement is fully visible in the viewport.

  • Kind: global function
  • Syntax: isElementInViewport(element)
  • Returns: boolean - the query result
Param Type Description
element HTMLElement | undefined target element

isElementsArray

Checks if an object is an Array in which all items are HTMLElement.

  • Kind: global function
  • Syntax: isElementsArray(object)
  • Returns: boolean - the query result
Param Type Description
object any | undefined the target object

isFunction

Checks if an object is a Function instance.

  • Kind: global function
  • Syntax: isFunction(object)
  • Returns: boolean - the query result
Param Type Description
object any the target object

isHTMLCollection

Checks if an object is an HTMLCollection instance.

  • Kind: global function
  • Syntax: isHTMLCollection(object)
  • Returns: boolean - the query result
Param Type Description
object any | undefined the target object

isHTMLElement

Checks if an element is an HTMLElement instance.

  • Kind: global function
  • Syntax: isHTMLElement(element)
  • Returns: boolean - the query result
Param Type Description
element any | undefined the target object

isHTMLImageElement

Check if a target element is an HTMLImageElement instance or <img>.

  • Kind: global function
  • Syntax: isHTMLImageElement(element)
  • Returns: boolean - the query result
Param Type Description
element any the target element

isMap

Checks if an element is a Map instance.

  • Kind: global function
  • Syntax: isMap(element)
  • Returns: boolean - the query result
Param Type Description
element any | undefined the target object

isMedia

Checks if an element is an <svg> (or any type of SVG element), <canvas>, <img> or <video>.

  • Kind: global function
  • Syntax: isMedia(element)
  • Returns: boolean - the query result
Param Type Description
element any | undefined the target element

isNode

Checks if an object is a Node instance.

  • Kind: global function
  • Syntax: isNode(node)
  • Returns: boolean - the query result
Param Type Description
node any | undefined the target object

isNodeList

Checks if an object is a NodeList.

  • Kind: global function
  • Syntax: isNodeList(object)
  • Returns: boolean - the query result
Param Type Description
object any | undefined the target object

isNumber

Shortie for typeof SOMETHING === number check.

  • Kind: global function
  • Syntax: isNumber(str)
  • Returns: boolean - the query result
Param Type Description
str any | undefined the input value

isObject

Shortie for typeof SOMETHING === object check.

  • Kind: global function
  • Syntax: isObject(obj)
  • Returns: boolean - the query result
Param Type Description
obj any | undefined the input value

isRTL

Checks if a page is Right To Left Language. If an optional Node parameter is provided, the utility will look at it's containing <html> parent's dir attribute value.

  • Kind: global function
  • Syntax: isRTL(node)
  • Returns: boolean - the query result
Param Type Description
node Node an optional node element

isScaledElement

Checks if a target HTMLElement is affected by scale.

  • Kind: global function
  • Syntax: isScaledElement(element)
  • Returns: boolean - the query result
Param Type Description
element HTMLElement | undefined the query result

isShadowRoot

Check if target is a ShadowRoot instance.

  • Kind: global function
  • Syntax: isShadowRoot(node)
  • Returns: boolean - the query result
Param Type Description
node any | undefined target element

isString

Shortie for typeof SOMETHING === string check.

  • Kind: global function
  • Syntax: isString(str)
  • Returns: boolean - the query result
Param Type Description
str any | undefined the input value

isSVGElement

Check if an element is an <svg> or any other SVG element.

  • Kind: global function
  • Syntax: isSVGElement(element)
  • Returns: boolean - the query result
Param Type Description
element any | undefined the target element

isTableElement

Check if a target element is a <table>, <td> or <th>.

  • Kind: global function
  • Syntax: isTableElement(element)
  • Returns: boolean - the query result
Param Type Description
element any | undefined the target element

isWeakMap

Checks if an element is a isWeakMap instance.

  • Kind: global function
  • Syntax: isWeakMap(element)
  • Returns: boolean - the query result
Param Type Description
element any | undefined the target object

isWindow

Check if a target object is a Window instance.

  • Kind: global function
  • Syntax: isWindow(object)
  • Returns: boolean - the query result
Param Type Description
object any | undefined the target object

Miscellaneous (src/misc)

ArrayFrom

Shortie for Array.from() static method. The utility should also work with any typed arrays like Float64Array or Int32Array.

  • Kind: global function
  • Syntax: ArrayFrom(array)
  • Returns: Array<any>
Param Type Description
array ArrayLike | Iterable array-like iterable object

createElement

Shortie for document.createElement method which allows you to create a new HTMLElement for a given tagName or based on an object with specific non-readonly attributes with string values: id, className, textContent, style, etc.

If no compatible parameter value is provided it returns undefined.

  • Kind: global function
  • Syntax: createElement(param)
  • Returns: HTMLElement | undefined
Param Type Description
param string | Partial<HTMLElement> tagName or an object with specific attributes

createElementNS

Shortie for the document.createElementNS static method which is similar to the one above, except that the first parameter is expected to be a namespaceURI string specific to your element.

  • Kind: global function
  • Syntax: createElementNS(namespace, param)
  • Returns: HTMLElement
Param Type Description
namespace string namespaceURI to associate with the newly created HTMLElement
param string | Partial<HTMLElement> tagName or an object with specific attributes

As a quick example create a new <svg> element you can do one of the following:

  • specify only the namespace and tagname:
const mySVGElement = createElementNS('http://www.w3.org/2000/svg', 'svg');
  • provide an object with specific attributes, but the tagName attribute is required:
const mySVGElement = createElementNS('http://www.w3.org/2000/svg', {
  tagName: 'SVG', // REQUIRED
  xmlns: 'http://www.w3.org/2000/svg',
  className: 'menu-icon',
});

Data

An interface for web components background data.

Data.set

Sets web components data.

  • Kind: static method of Data
  • Syntax: Data.set(target, component, instance)
  • Returns: void
Param Type Description
target HTMLElement target element
component string the component's name or a unique key
instance Record<string, any> the component instance

Data.getAllFor

Returns all instances for specified component or a unique key.

  • Kind: static method of Data
  • Syntax: Data.getAllFor(component)
  • Returns: Map<HTMLElement, object> | null - all the component instances
Param Type Description
component string the component's name or a unique key

Data.get

Returns the instance associated with a target element.

  • Kind: static method of Data
  • Syntax: Data.get(target, component)
  • Returns: object - the component instance
Param Type Description
target HTMLElement target element
component string the component's name or a unique key

Data.remove

Removes web components data.

  • Kind: static method of Data
  • Syntax: Data.remove(target, component)
  • Returns: void
Param Type Description
target HTMLElement target element
component string the component's name or a unique key

dispatchEvent

Shortie for the EventTarget.dispatchEvent() method.

  • Kind: global function
  • Syntax: dispatchEvent(element, event)
  • Returns: boolean which is the return of the EventTarget.dispatchEvent() method call.
Param Type Description
element EventTarget the target element
event Event is the Event object

distinct

JavaScript Array distinct, useful for filtering duplicate Array items.

Param Type Description
value any array item value
index number array item index
arr any a clone of the target array

emulateAnimationEnd

Utility to make sure callbacks are consistently called when keyframe animation ends. If the event isn't triggered for any reason, it has a fallback mechanism that triggers the event after the transitionDuration + transitionDelay period has expired.

  • Kind: global function
  • Syntax: emulateAnimationEnd(element, handler)
  • Returns: void
Param Type Description
element HTMLElement the target element
handler EventListener is your regular (event) => void event listener callback

emulateTransitionEnd

Utility to make sure callbacks are consistently called when transition ends. The utility has a similar fallback mechanism with the above emulateAnimationEnd.

  • Kind: global function
  • Syntax: emulateTransitionEnd(element, handler)
  • Returns: void
Param Type Description
element HTMLElement the target element
handler EventListener is your regular (event) => void event listener callback

Float32ArrayFrom

Shortie for Float32Array.from() static method.

  • Kind: global function
  • Syntax: Float32ArrayFrom(arr)
  • Returns: Float32Array
Param Type Description
arr ArrayLike<number> | Iterable<number> array-like iterable object

Float64ArrayFrom

Shortie for Float64Array.from() static method.

  • Kind: global function
  • Syntax: Float64ArrayFrom(arr)
  • Returns: Float64Array
Param Type Description
arr ArrayLike<number> | Iterable<number> array-like iterable object

focus

Shortie for HTMLElement.focus() method.

  • Kind: global function
  • Syntax: focus(element, options)
  • Returns: void
Param Type Description
element HTMLElement | SVGElement target element
options FocusOptions allows to pass additional options such as preventScroll: boolean

noop

Shortie for () => {} which is a generic function with empty body.

  • Kind: global function
  • Syntax: noop()
  • Returns: void

noop()

A generic function with empty body. Usually looks like () => {}.

  • Kind: global function

normalizeOptions

Utility to normalize web component options.

Param Type Description
element HTMLElement target element
defaultOps Record<string, any> the component's default options
inputOps Record<string, any> the component's instance options
namespace string the component's namespace designation

ObjectAssign

Shortie for Object.assign() static method.

  • Kind: global function
  • Syntax: ObjectAssign(object, source)
  • Returns: object
Param Type Description
object object a target object
source object | object[] a source object or array of objects

Examples:

// a single object source
ObjectAssign({ a: 1, b: 2 }, { c: 3 });
// => { a: 1, b: 2, c: 3 }

// multiple object sources
ObjectAssign({}, { a: 1, b: 2 }, { c: 3 });
// => { a: 1, b: 2, c: 3 }

ObjectEntries

Shortie for Object.entries() static method. The output values should match the types of the target object.

  • Kind: global function
  • Syntax: ObjectEntries(object)
  • Returns: Array<[key, value]>
Param Type Description
object object a target object

ObjectKeys

Shortie for Object.keys() static method. Again, the output keys should match the types of the target object.

  • Kind: global function
  • Syntax: ObjectKeys(object)
  • Returns: Array<string>
Param Type Description
object object a target object

ObjectValues

Shortie for Object.values() static method. Also, the output matches the value types of the target object.

  • Kind: global function
  • Syntax: ObjectValues(object)
  • Returns: Array<any>
Param Type Description
object object a target object

OriginalEvent

Returns a namespaced CustomEvent specific to a web component and enables adding additional event properties.

  • Kind: global function
  • Syntax: OriginalEvent(EventType, config)
  • Returns: CustomEvent a new namespaced event
Param Type Description
EventType string the custom event name
config object additional specific event properties

passiveHandler

A global namespace for most scroll event listeners, an object with passive: true value.

  • Kind: global constant

reflow

Utility to force re-paint of an HTMLElement target.

  • Kind: global function
  • Syntax: reflow(element)
  • Returns: number the target's offsetHeight
Param Type Description
element HTMLElement target element

setElementStyle

Shortie for multiple uses of HTMLElement.style.propertyName method. The utility should also work with special prefixed properties or CSS4 variables.

  • Kind: global function
  • Syntax: setElementStyle(element, styles)
  • Returns: void
Param Type Description
element HTMLElement target element
styles Partial<CSSStyleDeclaration> An object with multiple style rules.

Examples:

// your usual CSS properties
setElementStyle(target, { margin: '1rem', display: 'inline' });

// or special properties
setElementStyle(target, { '-webkit-transition': 'all 0.5s ease', '--my-custom-color': '#053' });

Timer

An interface that allows adding one or more TimerHandlers per HTMLElement. This comes in handy if you want to check if the callback was fired at any time.

Timer.set

Sets a new timeout timer for an element, or element -> key association.

  • Kind: static method of Timer
  • Syntax: Timer.set(target, callback, delay, key)
  • Returns: void
Param Type Description
target HTMLElement target element
callback TimerHandler the timeout callback
delay number the execution delay
key string | undefined an optional unique key

Timer.get

Returns the timer associated with the target.

  • Kind: static method of Timer
  • Syntax: Timer.get(target, key)
  • Returns: number - the timer
Param Type Description
target HTMLElement target element or selector
key string | undefined an optional unique key

Timer.clear

Clears the element's timer.

  • Kind: static method of Timer
  • Syntax: Timer.clear(target, key)
  • Returns: void
Param Type Description
target HTMLElement target element or selector
key string | undefined an optional unique key

toLowerCase

Shortie for String.toLowerCase().

  • Kind: global function
  • Syntax: toLowerCase(source)
  • Returns: string - lowercase output string
Param Type Description
source string input string

toUpperCase

Shortie for String.toUpperCase().

  • Kind: global function
  • Syntax: toUpperCase(source)
  • Returns: string - uppercase output string
Param Type Description
source string input string

selectors (src/selectors)

closest

Shortie for HTMLElement.closest method which also works with children of ShadowRoot. The order of the parameters is intentional since they're both required.

Param Type Description
element HTMLElement | Element target element
selector string the parent selector

getCustomElements

Returns an Array of Node elements that are registered as CustomElement.

  • Kind: global function
  • Syntax: getCustomElements(parent)
  • Returns: Array<HTMLElement>
Param Type Description
parent ParentNode | Document parent element

getElementById

Shortie for document.getElementById which returns an HTMLElement from the document that matches the given id. When an optional node parameter is provided, the utility will look into the document of that node.

  • Kind: global function
  • Syntax: getElementById(id, parent)
  • Returns: HTMLElement
Param Type Description
id string element id
context ParentNode | Document optional context node

getElementsByClassName

Shortie for document.getElementsByClassName which returns an HTMLCollection from the document or a given parent element.

  • Kind: global function
  • Syntax: getElementsByClassName(className, parent)
  • Returns: HTMLCollectionOf<HTMLElement>
Param Type Description
className string class name
parent ParentNode | Document parent element

getElementsByTagName

Shortie for document.getElementsByTagName which returns an HTMLCollection from the document or a given parent element.

  • Kind: global function
  • Syntax: getElementsByTagName(tagName, parent)
  • Returns: HTMLCollectionOf<HTMLElement>
Param Type Description
tagName string element tag name
parent ParentNode | Document parent element

matches

Shortie for Element.matches which checks if a target element matches a given selector.

  • Kind: global function
  • Syntax: matches(tagName, selector)
  • Returns: boolean
Param Type Description
tagName Element target element
selector string selector to match

querySelector

Utility to check if target is typeof Node or find one that matches a given selector.

  • Kind: global function
  • Syntax: querySelector(selector, parent)
  • Returns: HTMLElement | null
Param Type Description
selector string any valid selector string
parent ParentNode | Document parent element

querySelectorAll

A shortie for (document|Element).querySelectorAll.

  • Kind: global function
  • Syntax: querySelectorAll(selector, parent)
  • Returns: NodeListOf<HTMLElement>
Param Type Description
selector string any valid selector string
parent ParentNode | Document parent element
Clone this wiki locally