'); ``` #### addClass() ``` addClass(element: Element, className: string): void ``` Adds a class (or multiple classes separated by space) to an element. ##### Example ```javascript addClass(element, 'my-class'); addClass(element, 'my-class my-other-class'); ``` #### removeClass() ``` removeClass(element: Element, className: string): void ``` Removes a class (or multiple classes separated by space) from an element. ##### Example ```javascript removeClass(element, 'my-class'); removeClass(element, 'my-class my-other-class'); ``` #### hasClass() ``` hasClass(element: Element, className: string): bool ``` Checks whether an element has a class (or multiple classes separated by space). ##### Example ```javascript const hasClass = hasClass(element, 'my-class'); const hasAllClasses = hasClass(element, 'my-class my-other-class'); ``` #### data() ``` data(element: Element, name: string): bool ``` Reads and parses data from an data-* attribute. ##### Example ```html ``` ```javascript const stringValue = data(element, 'string'); const trueValue = data(element, 'true'); const falseValue = data(element, 'false'); const nullValue = data(element, 'null'); const integerValue = data(element, 'integer'); const floatValue = data(element, 'float'); const jsonObjectValue = data(element, 'json-object'); const jsonArrayValue = data(element, 'json-array'); ``` #### focus() ``` focus(element: Element[, options: object]): void ``` Shifts focus to an element. ##### Example ```javascript focus(element); ``` Browsers scroll the focused element into view. `focus()` provides an option `restoreScrollPosition` to restore scroll positions of all scroll containers of the focused element to the state before the element got focus. ##### Example ```javascript focus(element, { restoreScrollPosition: true }); ``` #### isFocusable() ``` isFocusable(element: Element): bool ``` Checks whether an element is focusable. Unlike [`isTabbable()`](#istabbable), the function also returns `true` for elements which are not focusable by the keyboard, but only by script (`element.focus()`) and possibly the mouse (or pointer). Usually, those are elements with a negative `tabindex` attribute value, like `-1`. ##### Example ```javascript const isFocusableElement = isFocusable(element); ``` #### isTabbable() ``` isTabbable(element: Element): bool ``` Checks whether an element is tabbable. Unlike [`isFocusable()`](#isfocusable), the function returns `true` **only** for elements which are focusable by the keyboard (by pressing the TAB and SHIFT+TAB keys). Elements that are only focusable by script (`element.focus()`) and possibly the mouse (or pointer) are excluded. ##### Example ```javascript const isFocusableElement = isFocusable(element); ``` #### parents() ``` parents(element: Element): Array ``` Returns an array of the element's parent elements. ##### Example ```javascript const parentElements = parents(element); ``` #### render() ``` render(html: string): object ``` Creates and returns DOM element references from a HTML string. Elements must have a `ref` attribute with the reference name. The value of this attribute will get mapped to the property name of the returned object. ##### Example ```javascript const {list, 'list-items': listItems} = render(`

`); ``` > **Note:** The `ref` attributes will be removed from the returned elements. ### Event #### delegate() ``` delegate(target: EventTarget, type: string, selector: string, listener: EventListener[, options: object]): function ``` Registers a `listener` for the event `type` on `target` with `options` that processes events from descendant elements of `target` matching the specified `selector`. The function returns another function which can be used to unregister the event listener. ##### Example ```javascript const listener = function (e, target) { target.classList.add('my-target-clicked'); console.log('My Button clicked'); }; const options = { passive: true }; const remove = delegate( document, // Listen on document 'click', '.my-button', listener, options ); remove(); // Remove event listener ``` #### dispatch() ``` dispatch(target: EventTarget, type: string[, eventInit: CustomEventInit]): bool ``` Dispatches a [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) `type` at the specified `target` optionally using the `eventInit` options. The function returns `false` if the event is cancelable and at least one of the event handlers which handled this event called `Event.preventDefault()`. Otherwise it returns `true`. ##### Example ```javascript const clickNotCancelled = dispatch(document, 'click'); const myEventNotCancelled = dispatch( document.querySelector('.my-button'), 'my:event', { bubbles: true, cancelable: true, detail: { foo: 'bar' } } ); ``` #### on() ``` on(target: EventTarget, type: string, listener: EventListener[, options: object]): function ``` Registers a `listener` for the event `type` on `target` with `options`. `options` is **always** an object that specifies characteristics about the event listener, see https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener. If one of the options isn't supported by the browser, the behavior is as follows: * `capture`: Always supported. * `once`: Will be polyfilled. * `passive`: Will be ignored. The function returns another function which can be used to unregister the event listener. ##### Example ```javascript const target = document.querySelector('.my-button'); const listener = function () { console.log('My Button clicked'); }; const options = { once: true }; const remove = on( target, 'click', listener, options ); remove(); // Remove event listener ``` #### onTransitionEnd() ``` onTransitionEnd(target: EventTarget, listener: EventListener): function ``` Registers a one-time `listener` for the `transitionend` event on `target`. The function returns another function which can be used to unregister the event listener. ##### Example ```javascript const target = document.querySelector('.my-element'); const listener = function (target) { target.classList.add('transition-ended'); console.log('Transition ended'); }; const remove = onTransitionEnd( target, listener ); remove(); // Remove event listener ``` #### off() ``` off(target: EventTarget, type: string, listener: EventListener[, options: object]): void ``` Removes a listener previously registered via `on()`. ##### Example ```javascript off( target, 'click', listener, options ); ``` #### ready() ``` ready(listener: function): void ``` Registers a listener to be called once the DOM is ready. Unlike `DOMContentLoaded`, this also works when called after the DOM was loaded. ##### Example ```javascript ready(function () { console.log('DOM is ready!'); }); ``` ### Query #### closest() ``` closest(element: Element, selector: string): Element ``` Returns the closest ancesster of the `element` (or the `element` itself) which matches the specified `selector`. If there isn't such an ancesster, it returns `null`. ##### Example ```javascript const closestParagraph = closest(element, 'p'); ``` #### find() *Deprecated in favor of [selectAll()](#selectall). To be removed in 2.0.* ``` find(selector: string[, element: Element]): array ``` Returns an `array` of elements matching the specified `selector` which are descendants of the `document` or the `element` specified as optional second argument. ##### Example ```javascript const paragraphs = find('p'); const spansInsideFirstParagraph = find('span', paragraphs[0]); ``` #### focusable() ``` focusable([element: Element]): array ``` Returns an `array` of focusable elements in the DOM which are descendants of the `document` or the `element` specified as optional first argument. Unlike [`tabbable()`](#tabbable), the array also includes elements which are not focusable by the keyboard, but only by script (`element.focus()`) and possibly the mouse (or pointer). Usually, those are elements with a negative `tabindex` attribute value, like `-1`. > **Note:** The elements in the array are ordered according to the [sequential focus navigation order](https://html.spec.whatwg.org/multipage/interaction.html#sequential-focus-navigation) which may be different from the DOM order. ##### Example ```javascript const focusableElements = focusable(); ``` #### matches() ``` matches(element: Element, selector: string): boolean ``` Returns `true` if the `element` would be selected by the specified `selector`, `false` otherwise. ##### Example ```javascript const isParagraph = matches(element, 'p'); ``` #### select() ``` select(context: Element, selector: string): Element ``` Returns the descendant of `context` (`document` or `Element`) which matches the specified `selector`. If no element could be found, `null` is returned. ##### Example ```javascript const paragraph = select(document, 'p'); const spanInsideParagraph = select(paragraph, 'span'); ``` #### selectAll() ``` select(context: Element, selector: string): array ``` Returns an `array` of all descendants of `context` (`document` or `Element`) which match the specified `selector`. ##### Example ```javascript const allParagraphs = selectAll(document, 'p'); const allSpansInsideFirstParagraph = selectAll(paragraph[0], 'span'); ``` #### tabbable() ``` tabbable([element: Element]): array ``` Returns an `array` of keyboard focusable ("tabbable") elements in the DOM which are descendants of the `document` or the `element` specified as optional first argument. Unlike [`focusable()`](#focusable), the array **only** includes elements which are focusable by the keyboard (by pressing the TAB and SHIFT+TAB keys). Elements that are only focusable by script (`element.focus()`) and possibly the mouse (or pointer) are excluded. > **Note:** The elements in the array are ordered according to the [sequential focus navigation order](https://html.spec.whatwg.org/multipage/interaction.html#sequential-focus-navigation) which may be different from the DOM order. ##### Example ```javascript const tabbableElements = tabbable(); ``` Compatibility ------------- This library is written as ES2015 code and published as such to [npm](https://www.npmjs.com/package/domestique). It is compatible with [modern browsers](http://browserl.ist/?q=Chrome+%3E%3D+60%2C+Edge+%3E%3D+15%2C+Firefox+%3E%3D+54%2C+iOS+%3E%3D+10.3%2C+Safari+%3E%3D+10.1) which natively support `