Lodash for the DOM
Peso is a collection of composable functions for easy DOM manipulation. These functions are simple wrappers around the native DOM APIs to facilitate a functional programming style and they work seamlessly with lodash.
# with npm
npm install peso --save
# with yarn
yarn add peso
The preferred way to use peso in your project is to import only the functions that are needed.
import { $, addClass } from "peso";
You can also import all functions at once.
import * as peso from "peso";
// every function is available under peso, e.g.
// peso.$, peso.addClass
$, $$, addClass, addListener, after, append, appendTo, before, children, clone, closest, createElement, createFragment, createText, delegate, findAll, findOne, forceClass, get, getAttr, getData, getStyle, hasClass, insertAfter, insertBefore, matches, measure, parent, prepend, prependTo, qs, qsa, remove, removeAttr, removeClass, removeData, removeListener, replace, replaceWith, set, setAttr, setData, setStyle, toggleClass
$(selector)
Returns the first element matching the selector string. The result can then be passed to other peso functions as the last parameter.
The first element matched by the selector
$$(selector)
Returns an array containing all elements matching the selector string. The result can then be mapped through other peso functions. See TODO
An array containing all elements matched by the selector
addClass(className)(item)
Adds the specified class name(s) to the element.
className: string
the class name(s) to add
item: Element
the target element
Element
- the item
addListener(options)(listener)(event)(item)
Adds an event listener to the item.
EventListenerOptions
- event listener optionsEvent => void
- the event listenerstring
- the event typeElement | Text | Document | DocumentFragment | Window
- the itemElement | Text | Document | DocumentFragment | Window
- the item
after(subject)(item)
Inserts the subject after the item.
subject: Element | Text | DocumentFragment | string
the subject to insert after the item
item: Element | Text
- the item
Element | Text
- the item
append(subject)(item)
Appends the subject as the last child of the item.
subject: Element | Text | DocumentFragment | string
the subject to append to the item
item: Element | Document | DocumentFragment
- the item
Element | Text| Document | DocumentFragment
- the item
appendTo(target)(item)
Appends the item as the last child of the target.
target: Element | Document | DocumentFragment
the target to append the item to
item: Element | Text | DocumentFragment | string
- the item
Element | Text | DocumentFragment | string
- the item
before(subject)(item)
Inserts the subject before the item.
subject: Element | Text | DocumentFragment | string
the subject to insert before the item
item: Element | Text
- the item
Element | Text
- the item
children(item)
Returns the child elements of the item.
Element | Document | DocumentFragment
Element[]
- the children of the item
clone(deep)(item)
Clones the item.
deep: boolean
- perform a deep clone (default: false)
item: Element | Text | Document | DocumentFragment
- the item
Element | Text | Document | DocumentFragment
- the clone of the item
closest(selector)(item)
Returns the closest ancestor of the item that matches the selector.
string
- the selector stringElement
Element | null
- the ancestor
createElement(type)
Creates a new HTML element.
string
- the type of the elementElement
the created element
createFragment()
Creates a new document fragment.
DocumentFragment
the created document fragment
createText(content)
Creates a new text node.
string
- the content of the text nodeText
the created text node
delegate(listener)(selector)
Delegates an event listener for descendant elements that match the selector.
(e: Event) => void
- the event listener function to delegatestring
- the selector that the descendant elements need to match to trigger the listener(e: Event) => void
- the delegated event listener function
findAll(selector)(item)
Finds all descendants that match the selector.
string
- the selector to matchElement | Document | DocumentFragment
- the itemElement[]
- the matched descendants
findOne(selector)(item)
Finds the first descendant that matches the selector.
string
- the selector to matchElement | Document | DocumentFragment
- the itemElement | null
- the match
forceClass(className)(force)(item)
Toggles a class name of the item.
string
- the class name to toggle?boolean
- force adding or removing the class nameElement
- the itemboolean
- indicates if the element has the class name after the call
(If you need to return the element instead, use toggleClass)
get(property)(item)
Gets the specified property of the item.
string
- the name of the propertyElement
- the itemstring
- the value of the property
getAttr(attribute)(item)
Gets the specified attribute of the item.
string
- the name of the attributeElement
- the itemstring
- the value of the attribute
getData(key)(item)
Gets the specified data-attribute of the item.
string
- the key of the data-attributeHTMLElement
- the itemstring
- the value of the data-attribute
getStyle(name)(item)
Gets the specified style of the item
string
- the name of the style ruleElement
- the itemstring
- the value of the style rule
hasClass(className)(item)
Determine if the class name is assigned to the item.
string
- the class nameElement
- the itemboolean
insertAfter(target)(item)
Inserts the item after the target element.
Element | Text
- the targetElement | Text | DocumentFragment | string
- the itemElement | Text | DocumentFragment
- the item
insertBefore(target)(item)
Inserts the item before the target element.
Element | Text
- the targetElement | Text | DocumentFragment | string
- the itemElement | Text | DocumentFragment
- the item
matches(selector)(item)
Checks if the item would be selected by the provided selector.
string
- the selector to matchElement
- the itemboolean
- the match
measure(item)
Measures the item and returns its DOMRect.
Element
- the itemDOMRect
- the DOMRect of the item
parent(item)
Returns the parent element of the item.
Element | Text | Document | DocumentFragment
- the itemElement | null
- the parent of the item
prepend(subject)(item)
Prepends the subject as the first child of the item.
subject: Element | Text | DocumentFragment | string
the subject to prepend to the item
item: Element | Document | DocumentFragment
- the item
Element | Text| Document | DocumentFragment
- the item
prependTo(target)(item)
Prepends the item as the first child of the target.
target: Element | Document | DocumentFragment
the target to prepend the item to
item: Element | Text | DocumentFragment | string
- the item
Element | Text | DocumentFragment | string
- the item
qs(selector)
Returns the first element matching the selector string. The result can then be passed to other peso functions as the last parameter.
The first element matched by the selector
qsa(selector)
Returns an array containing all elements matching the selector string. The result can then be mapped through other peso functions. See TODO
An array containing all elements matched by the selector
remove(item)
Removes the item from the DOM.
Element | Text
- the itemvoid
removeAttr(attribute)(item)
Removes the specified attribute from the item.
string
- the attribute to removeElement
- the itemElement
- the item
removeClass(className)(item)
Removes the specified class name from the item.
string
- the class name to removeElement
- the itemElement
- the item
removeData(key)(item)
Removes a data-attribute of the item.
string
- the data key to removeHTMLElement
- the itemHTMLElement
- the item
removeListener(options)(listener)(event)(item)
Removes an event listener from the item.
EventListenerOptions
- event listener optionsEvent => void
- the event listenerstring
- the event typeElement | Text | Document | DocumentFragment | Window
- the itemElement | Text | Document | DocumentFragment | Window
- the item
replace(target)(item)
Replaces the target with the item.
Element | Text
- the target that will be replacedElement | Text | DocumentFragment | string
- the itemElement | Text | DocumentFragment
- the item
replaceWith(subject)(item)
Replaces the item with the subject.
Element | Text | DocumentFragment | string
- the subjectElement | Text
- the item that will be replacedElement | Text
- the item that was replaced
set(property)(value)(item)
Sets a property of the item.
{ [attribute: string]: string }
- an object containing the attribute names and values to setElement
- the itemElement
- the item
setAttr(attributes)(item)
Sets one or more attributes of the item.
{ [attribute: string]: string }
- an object containing the attribute names and values to setElement
- the itemElement
- the item
setData(data)(item)
Sets one or more data-attributes of the item.
{ [key: string]: string }
- an object containing the data keys and values to setElement
- the itemElement
- the item
setStyle(styles)(item)
Sets one or more styles of the item.
{ [property: string]: string }
- an object containing the style properties and values to setElement
- the itemElement
- the item
string
- the text contentText
- the created text node
toggleClass(className)(force)(item)
Toggles a class name of the item.
string
- the class name to toggle?boolean
- force adding or removing the class nameElement
- the itemElement
- the item
(If you need to return the result of the toggle, use forceClass)
MIT License