@olmokit/dom

Other

AnyDOMEvent

Ƭ AnyDOMEvent<TType>: TType extends StandardDOMEventTypes ? GlobalEventHandlersEventMap[TType] : TType extends "storage" ? StorageEvent : TType extends "popstate" ? PopStateEvent : Event

Type parameters

Name	Type
TType	extends AnyDOMEventType

Defined in

dom/types.ts:19

---

AnyDOMEventTarget

Ƭ AnyDOMEventTarget: Window | Document | HTMLElement | Element

Defined in

dom/types.ts:4

---

AnyDOMEventTargetLoose

Ƭ AnyDOMEventTargetLoose: AnyDOMEventTarget | AnythingFalsy

We use it either throwing an error on unexisting element or falling back to window in case of scroll or resize events

Defined in

dom/types.ts:10

---

AnyDOMEventType

Ƭ AnyDOMEventType: LiteralUnion<StandardDOMEventTypes | "storage" | "popstate", string>

Defined in

dom/types.ts:14

---

$

▸ $<T>(selector, parent?, avoidEscape?): T

Sizzle/jQuery like DOM nodes shortcut for document.querySelector To avoid an extra function call we inline the above escape

Type parameters

Name	Type
T	extends Element = HTMLElement

Parameters

Name	Type	Description
selector	string	DOM selector
parent?	null | HTMLElement | Document	It falls back to window.document
avoidEscape?	boolean	Whether to avoid escaping : in the selector string

Returns

T

Example

Basic DOM selection

const $container = $(".my-section:");
const $el = $("[data-some-attr]", $container);

Defined in

dom/$.ts:12

---

$all

▸ $all<T>(selector, parent?, avoidEscape?): NodeListOf<T>

Sizzle/jQuery like DOM nodes shortcut for document.querySelectorAll To avoid an extra function call we inline the above escape

Type parameters

Name	Type
T	extends Element = HTMLElement

Parameters

Name	Type	Description
selector	string	-
parent?	null | Element | HTMLElement | Document	It falls back to window.document
avoidEscape?	boolean	Whether to avoid escaping : in the selector string

Returns

NodeListOf<T>

Defined in

dom/$all.ts:9

---

$each

▸ $each<T>(selector, callback, parent?, scope?): void

Each shortcut, iterate through a NodeList of HTMLElements retrieved with the given selector (and optionally a parent container passed as thrid arguement)

Type parameters

Name	Type
T	extends Element = HTMLElement

Parameters

Name	Type	Description
selector	string	DOM selector
callback	($element: T, index: number) => any
parent?	HTMLElement	It falls back to window.document
scope?	object

Returns

void

Defined in

dom/$each.ts:12

---

addClass

▸ addClass<T>(el?, className?): void

Add class shortcut

Type parameters

Name	Type
T	extends Element = HTMLElement

Parameters

Name	Type	Default value
el?	T	undefined
className	string	""

Returns

void

Defined in

dom/addClass.ts:4

---

calculateFixedOffset

▸ calculateFixedOffset(selector?): number

Parameters

Name	Type	Default value
selector	string	"[data-fixed]"

Returns

number

Defined in

dom/calculateFixedOffset.ts:3

---

createElement

▸ createElement<TType, TElement>(type, className?): TElement

Shortcut for document.createElement, allowing to to create an HTML element with a given className directly (a very common use case)

Type parameters

Name	Type
TType	extends LiteralUnion<keyof HTMLElementTagNameMap, string>
TElement	extends HTMLElement = TType extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[TType] : HTMLElement

Parameters

Name	Type
type	TType
className?	string

Returns

TElement

Defined in

dom/createElement.ts:8

---

emitEvent

▸ emitEvent(type?, detail?): void

Emit event (use only if the targeted browser supports CustomEvents)

Parameters

Name	Type	Default value
type	string	"customEvent"
detail	Object	{}

Returns

void

Defined in

dom/emitEvent.ts:4

---

escapeSelector

▸ escapeSelector(selector): string

Escape colons to allow use class names as .module:block__element

Parameters

Name	Type
selector	string

Returns

string

See

https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector#Escaping_special_characters

Defined in

dom/escapeSelector.ts:7

---

exists

▸ exists(node?): boolean

Checks if passed node exist and is a valid element.

Parameters

Name	Type
node?	Element

Returns

boolean

Borrows

@glidejs/glide/src/utils/dom (source)

Defined in

dom/exists.ts:6

---

forEach

▸ forEach<T, TScope>(nodes, callback, scope?): void

For each, iterate through a NodeList or an array of HTMLElements

Type parameters

Name	Type
T	extends HTMLElement
TScope	object

Parameters

Name	Type	Description
nodes	NodeListOf<T> | T[]	-
callback	(this: TScope, $element: T, index: number) => any	-
scope?	TScope	The optional this of the callback function

Returns

void

Defined in

dom/forEach.ts:6

---

getDataAttr

▸ getDataAttr(element, attribute): null | string

Get data attribute

Parameters

Name	Type	Description
element	HTMLElement
attribute	string	The name of the data-{attr}

Returns

null | string

Defined in

dom/getDataAttr.ts:10

---

getDocumentHeight

▸ getDocumentHeight(): number

Determine the document's height

Returns

number

See

https://github.com/cferdinandi/smooth-scroll (credits)

Defined in

dom/getDocumentHeight.ts:6

---

getHeight

▸ getHeight(element): number

Get element height

Parameters

Name	Type
element	HTMLElement

Returns

number

Defined in

dom/getHeight.ts:4

---

getOffset

▸ getOffset(elem): Object

Get an element's distance from the top and left of the Document.

Parameters

Name	Type	Description
elem	HTMLElement	The HTML node element

Returns

Object

Distance from the top and left in pixels

Name	Type
left	number
top	number

Defined in

dom/getOffset.ts:7

---

getOffsetTop

▸ getOffsetTop(elem): number

Get an element's distance from the top of the Document.

Parameters

Name	Type	Description
elem	HTMLElement	The HTML node element

Returns

number

Distance from the top in pixels

See

https://vanillajstoolkit.com/helpers/getoffsettop/

Defined in

dom/getOffsetTop.ts:9

---

getOffsetTopSlim

▸ getOffsetTopSlim(elem): number

Get an element's distance from the top of the Document (using more modern/performant technique compared to ./getOffsetTop)

Parameters

Name	Type	Description
elem	HTMLElement	The HTML node element

Returns

number

Distance from the top in pixels

See

https://stackoverflow.com/q/5598743/1938970

Defined in

dom/getOffsetTopSlim.ts:10

---

getScrollbarWidth

▸ getScrollbarWidth(element?): number

Get scrollbar's current width

Parameters

Name	Type
element?	HTMLElement

Returns

number

Defined in

dom/getScrollbarWidth.ts:4

---

getStyleValue

▸ getStyleValue(el, prop): string

Return the current style value for an element CSS property

Parameters

Name	Type	Description
el	HTMLElement	The element to compute
prop	string	The style property

Returns

string

Defined in

dom/getStyleValue.ts:7

---

getVisualBackgroundColor

▸ getVisualBackgroundColor(elem?): string

Get the background color of an element eventually looking recursively into its parents, if nothing is found it returns a #fff background

Parameters

Name	Type
elem?	null | HTMLElement

Returns

string

Defined in

dom/getVisualBackgroundColor.ts:5

---

injectCss

▸ injectCss(id, cssString?, root?): void

Inject css

Parameters

Name	Type	Default value
id	string	undefined
cssString	string	""
root	Document	document

Returns

void

Defined in

dom/injectCss.ts:4

---

isHidden

▸ isHidden(el?): boolean

Is element hidden?

Parameters

Name	Type
el?	HTMLElement

Returns

boolean

Defined in

dom/isHidden.ts:4

---

isInViewport

▸ isInViewport(elem): boolean

Determine if an element is in the viewport

Parameters

Name	Type	Description
elem	Element	The element

Returns

boolean

Returns true if element is in the viewport

Borrows

(c) 2017 Chris Ferdinandi, MIT License, https://gomakethings.com

Defined in

dom/isInViewport.ts:9

---

isNodeList

▸ isNodeList(nodes): nodes is NodeList

Is node list

Parameters

Name	Type	Description
nodes	any	The object to check

Returns

nodes is NodeList

Defined in

dom/isNodeList.ts:6

---

isTotallyScrolled

▸ isTotallyScrolled(el?): boolean

Is element totally scrolled

Parameters

Name	Type
el?	HTMLElement

Returns

boolean

See

• https://github.com/willmcpo/body-scroll-lock/blob/master/src/bodyScrollLock.js#L116
• https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollHeight#Problems_and_solutions

Defined in

dom/isTotallyScrolled.ts:7

---

listenLoaded

▸ listenLoaded(handler): void

Fires a callback when the DOM content is loaded

Parameters

Name	Type
handler	(event: Event) => any

Returns

void

See

https://mathiasbynens.be/notes/settimeout-onload

Defined in

dom/listenLoaded.ts:8

---

listenResize

▸ listenResize(handler, el?): () => void

Listen element's (window by default) scroll event

Parameters

Name	Type
handler	() => void
el?	AnyDOMEventTargetLoose

Returns

fn

An automatic unbinding function to run to deregister the listener upon call

▸ (): void

Returns

void

Defined in

dom/listenResize.ts:9

---

listenResizeDebounced

▸ listenResizeDebounced(el?, ...args): () => void

Listen element's (window by default) resize event debouncing the callback

Parameters

Name	Type
el?	AnyDOMEventTargetLoose
...args	[fn: Function, wait?: number, immediate?: boolean]

Returns

fn

An automatic unbinding function to run to deregister the listener upon call

▸ (): void

Returns

void

Defined in

dom/listenResizeDebounced.ts:9

---

listenResizeThrottled

▸ listenResizeThrottled(el?, ...args): () => void

Listen element's (window by default) resize event throttling the callback

Parameters

Name	Type
el?	AnyDOMEventTargetLoose
...args	[fn: Function, limit: number, context?: unknown]

Returns

fn

An automatic unbinding function to run to deregister the listener upon call

▸ (): void

Returns

void

Defined in

dom/listenResizeThrottled.ts:9

---

listenScroll

▸ listenScroll(handler, el?): () => void

Listen element's (window by default) scroll event

Parameters

Name	Type
handler	() => void
el?	AnyDOMEventTargetLoose

Returns

fn

An automatic unbinding function to run to deregister the listener upon call

▸ (): void

Returns

void

Defined in

dom/listenScroll.ts:9

---

listenScrollDebounced

▸ listenScrollDebounced(el?, ...args): () => void

Listen element's (window by default) scroll event debouncing the callback

Parameters

Name	Type
el?	AnyDOMEventTargetLoose
...args	[fn: Function, wait?: number, immediate?: boolean]

Returns

fn

An automatic unbinding function to run to deregister the listener upon call

▸ (): void

Returns

void

Defined in

dom/listenScrollDebounced.ts:9

---

listenScrollThrottled

▸ listenScrollThrottled(el?, ...args): () => void

Listen element's (window by default) scroll event throttling the callback

Parameters

Name	Type
el?	AnyDOMEventTargetLoose
...args	[fn: Function, limit: number, context?: unknown]

Returns

fn

An automatic unbinding function to run to deregister the listener upon call

▸ (): void

Returns

void

Defined in

dom/listenScrollThrottled.ts:9

---

off

▸ off<TType>(el, type, handler, options?): void

Shortcut for removeEventListener

Type parameters

Name	Type
TType	extends AnyDOMEventType

Parameters

Name	Type	Default value
el	AnyDOMEventTargetLoose	undefined
type	TType	undefined
handler	(event: AnyDOMEvent<TType>) => void	undefined
options	boolean | EventListenerOptions	false

Returns

void

Defined in

dom/off.ts:10

---

on

▸ on<TType>(el, type, handler, options?): () => void

Shortcut for addEventListener

Type parameters

Name	Type
TType	extends AnyDOMEventType

Parameters

Name	Type	Default value
el	AnyDOMEventTargetLoose	undefined
type	TType	undefined
handler	(event: AnyDOMEvent<TType>) => void	undefined
options	boolean | AddEventListenerOptions	false

Returns

fn

An automatic unbinding function to run to deregister the listener upon call

▸ (): void

Returns

void

Defined in

dom/on.ts:14

---

onClickOutside

▸ onClickOutside(element, callback, autoUnbind?): () => void

Parameters

Name	Type	Default value
element	HTMLElement	undefined
callback	(event: Event) => any	undefined
autoUnbind	boolean	false

Returns

fn

▸ (): void

Returns

void

Defined in

dom/onClickOutside.ts:3

---

once

▸ once(el, type, handler, options?): () => void

One shot listener, it addEventListener and removes it first time is called with removeEventListener

Parameters

Name	Type	Default value
el	AnyDOMEventTargetLoose	undefined
type	string	undefined
handler	EventListener	undefined
options	boolean | EventListenerOptions	false

Returns

fn

▸ (): void

Returns

void

Defined in

dom/once.ts:9

---

removeClass

▸ removeClass<T>(el?, className?): void

Remove class shortcut

Type parameters

Name	Type
T	extends Element = HTMLElement

Parameters

Name	Type	Default value
el?	T	undefined
className	string	""

Returns

void

Defined in

dom/removeClass.ts:4

---

scrollTo

▸ scrollTo(destination, callback?, fallbackTimeout?, behavior?): void

Native scrollTo, "smooth" and with callback

Parameters

Name	Type	Description
destination	number	-
callback?	() => void	callback function
fallbackTimeout?	number	this appears to be needed in some hard to reproduce scenario on safari, where the callback seem to be never called
behavior?	ScrollBehavior

Returns

void

Borrows

https://stackoverflow.com/a/55686711/1938970

Defined in

dom/scrollTo.ts:14

---

setDataAttr

▸ setDataAttr(element, attribute, value?): void

Set data attribute

Parameters

Name	Type	Description
element	Element
attribute	string	The name of the data-{attr}
value?	null | string | number | boolean	The value to set, null or undefined will remove the attribute

Returns

void

Defined in

dom/setDataAttr.ts:8

---

setVendorCSS

▸ setVendorCSS(element, prop, value): void

Set vendor CSS rule

Parameters

Name	Type	Description
element	HTMLElement	A single HTMLElement
prop	string	CSS rule proerty
value	string | number | boolean	The CSS value to set, it will be automatically vendor prefixed

Returns

void

Defined in

dom/setVendorCSS.ts:8

---

siblings

▸ siblings(node): Element[]

Finds siblings nodes of the passed node.

Parameters

Name	Type
node	Element

Returns

Element[]

Borrows

@glidejs/glide/src/utils/dom (source)

Defined in

dom/siblings.ts:6

---

toArray

▸ toArray<T>(nodeList): T[] | HTMLFormElement[]

Node list to array

Type parameters

Name	Type
T	extends Element = HTMLElement

Parameters

Name	Type
nodeList	NodeListOf<T> | HTMLFormControlsCollection

Returns

T[] | HTMLFormElement[]

Defined in

dom/toArray.ts:6

listen-delegation

getListeners

▸ getListeners(): Partial<Record<AnyDOMEventType, ListenEvent[]>>

Get an immutable copy of all active event listeners

Returns

Partial<Record<AnyDOMEventType, ListenEvent[]>>

Active event listeners

Defined in

dom/getListeners.ts:10

---

listen

▸ listen<TTypes, TTarget>(types, selector, callback): void

Listen an event

Type parameters

Name	Type
TTypes	extends AnyDOMEventType
TTarget	extends AnyDOMEventTarget = AnyDOMEventTarget

Parameters

Name	Type	Description
types	TTypes	The event type or types (comma separated)
selector	string	The selector to run the event on
callback	EventCallback<TTarget, TTypes>	The function to run when the event fires

Returns

void

Defined in

dom/listen.ts:20

---

listenOnce

▸ listenOnce(types, selector, callback): void

Listen an event, and automatically unlisten it after it's first run

Parameters

Name	Type	Description
types	string	The event type or types (comma separated)
selector	string	The selector to run the event on
callback	EventCallback	The function to run when the event fires

Returns

void

Defined in

dom/listenOnce.ts:14

---

unlisten

▸ unlisten<TTypes, TTarget>(types, selector, callback): void

Stop listening for an event

Type parameters

Name	Type
TTypes	extends AnyDOMEventType
TTarget	extends AnyDOMEventTarget = AnyDOMEventTarget

Parameters

Name	Type	Description
types	TTypes	The event type or types (comma separated)
selector	string	The selector to remove the event from
callback	EventCallback<TTarget, TTypes>	The function to remove

Returns

void

Defined in

dom/unlisten.ts:19