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 pesoThe 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.
- selector (string) - the selector string to match
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
- selector (string) - the selector string to match
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.
- options:
EventListenerOptions- event listener options - listener:
Event => void- the event listener - event:
string- the event type - item:
Element | Text | Document | DocumentFragment | Window- the item
Element | 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.
- 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.
- selector:
string- the selector string - item:
Element
Element | null - the ancestor
createElement(type)
Creates a new HTML element.
- type:
string- the type of the element
Elementthe created element
createFragment()
Creates a new document fragment.
DocumentFragmentthe created document fragment
createText(content)
Creates a new text node.
- content:
string- the content of the text node
Textthe created text node
delegate(listener)(selector)
Delegates an event listener for descendant elements that match the selector.
- listener:
(e: Event) => void- the event listener function to delegate - selector:
string- 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.
- selector:
string- the selector to match - item:
Element | Document | DocumentFragment- the item
Element[] - the matched descendants
findOne(selector)(item)
Finds the first descendant that matches the selector.
- selector:
string- the selector to match - item:
Element | Document | DocumentFragment- the item
Element | null - the match
forceClass(className)(force)(item)
Toggles a class name of the item.
- className:
string- the class name to toggle - force:
?boolean- force adding or removing the class name - item:
Element- the item
boolean - 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.
- property:
string- the name of the property - item:
Element- the item
string - the value of the property
getAttr(attribute)(item)
Gets the specified attribute of the item.
- attribute:
string- the name of the attribute - item:
Element- the item
string - the value of the attribute
getData(key)(item)
Gets the specified data-attribute of the item.
- key:
string- the key of the data-attribute HTMLElement- the item
string - the value of the data-attribute
getStyle(name)(item)
Gets the specified style of the item
- name:
string- the name of the style rule - item:
Element- the item
string - the value of the style rule
hasClass(className)(item)
Determine if the class name is assigned to the item.
- className:
string- the class name - item:
Element- the item
boolean
insertAfter(target)(item)
Inserts the item after the target element.
- target:
Element | Text- the target - item:
Element | Text | DocumentFragment | string- the item
Element | Text | DocumentFragment - the item
insertBefore(target)(item)
Inserts the item before the target element.
- target:
Element | Text- the target - item:
Element | Text | DocumentFragment | string- the item
Element | Text | DocumentFragment - the item
matches(selector)(item)
Checks if the item would be selected by the provided selector.
- selector:
string- the selector to match - item:
Element- the item
boolean - the match
measure(item)
Measures the item and returns its DOMRect.
- item:
Element- the item
DOMRect - the DOMRect of the item
parent(item)
Returns the parent element of the item.
- item:
Element | Text | Document | DocumentFragment- the item
Element | 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.
- selector (string) - the selector string to match
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
- selector (string) - the selector string to match
An array containing all elements matched by the selector
remove(item)
Removes the item from the DOM.
- item:
Element | Text- the item
void
removeAttr(attribute)(item)
Removes the specified attribute from the item.
- attribute:
string- the attribute to remove - item:
Element- the item
Element - the item
removeClass(className)(item)
Removes the specified class name from the item.
- className:
string- the class name to remove - item:
Element- the item
Element - the item
removeData(key)(item)
Removes a data-attribute of the item.
- key:
string- the data key to remove - item:
HTMLElement- the item
HTMLElement - the item
removeListener(options)(listener)(event)(item)
Removes an event listener from the item.
- options:
EventListenerOptions- event listener options - listener:
Event => void- the event listener - event:
string- the event type - item:
Element | Text | Document | DocumentFragment | Window- the item
Element | Text | Document | DocumentFragment | Window - the item
replace(target)(item)
Replaces the target with the item.
- target:
Element | Text- the target that will be replaced - item:
Element | Text | DocumentFragment | string- the item
Element | Text | DocumentFragment - the item
replaceWith(subject)(item)
Replaces the item with the subject.
- subject:
Element | Text | DocumentFragment | string- the subject - item:
Element | Text- the item that will be replaced
Element | Text - the item that was replaced
set(property)(value)(item)
Sets a property of the item.
- attributes:
{ [attribute: string]: string }- an object containing the attribute names and values to set - item:
Element- the item
Element - the item
setAttr(attributes)(item)
Sets one or more attributes of the item.
- attributes:
{ [attribute: string]: string }- an object containing the attribute names and values to set - item:
Element- the item
Element - the item
setData(data)(item)
Sets one or more data-attributes of the item.
- data:
{ [key: string]: string }- an object containing the data keys and values to set - item:
Element- the item
Element - the item
setStyle(styles)(item)
Sets one or more styles of the item.
- styles:
{ [property: string]: string }- an object containing the style properties and values to set - item:
Element- the item
Element - the item
- content:
string- the text content
Text - the created text node
toggleClass(className)(force)(item)
Toggles a class name of the item.
- className:
string- the class name to toggle - force:
?boolean- force adding or removing the class name - item:
Element- the item
Element - the item
(If you need to return the result of the toggle, use forceClass)
MIT License