Menu Open

LDOM API Documentation

Getting Started

LDOM is a Lightweight (about 8% of the size of jQuery) way to interact with the browser DOM (Document Object Model). To start development, download the development version and include it in your webpage. Download ldom.dev.js 
<script src="ldom.dev.js"></script>
Once you are ready for production, you can run getLDOMFunctionUsage() in your browser console. This will show which features of LDOM you have used so far on the current page. Then you can customize your LDOM download to only include the features you need!
Be sure to interact with all of the features of your webpage to get an accurate usage list. Customize ldom.min.js
If you are familiar with jQuery, then LDOM will feel very similar. In many common use cases, LDOM can simply be a drop-in replacement to jQuery without any problems. LDOM is able to startup over 10x faster due to it's small size and simple code. One way that LDOM is so much smaller and simpler than jQuery is that it doesn't support all of the ancient browsers that jQuery does. That being said, by using LDOM, here are the minimum browser versions that are supported. (Basically any browser since 2013)
Browser Version
Chrome 29
Firefox 23
Safari 6
IE 9
Edge all
Opera 12

LDOM vs jQuery

There is never one correct library for all situations. It's important to know the pros and cons to help you make the best decision for your use-case.

LDOM > jQuery

  • Smaller library size allows for faster load times on slower networks.
    (8% of the size of jQuery)
  • Smaller/simpler library enables faster parse/compile time and therefore your code will start sooner.
    (10x faster startup time)
  • Customizable library lets you make the library even smaller if you don't want certain features.
    (85% possible size reduction)
  • Faster DOM Element creation.
  • All LDOM code clearly maps to VanillaJS code. No complicated wrappers or replacements of default DOM behavior.
  • Better library source code readability.

LDOM < jQuery

  • Less browser support.
  • Slower performance in extremely heavy tasks.

Example Usage

Comparison between LDOM and Vanilla JavaScript

Set the text of all buttons.

LDOM

$("button").text("I am a Button");

Vanilla JavaScript

var buttons = document.querySelectorAll("button");
for (var i = 0; i < buttons.length; i++) {
	buttons[i].innerText = "I am a Button";	
}

Add a class to all parents of buttons.

LDOM

$("button").parent().addClass("button-parent");

Vanilla JavaScript

var buttons = document.querySelectorAll("button");
for (var i = 0; i < buttons.length; i++) {
	if (buttons[i].parentNode.className.split(" ").indexOf("button-parent") === -1) {
		buttons[i].parentNode.className += " " + "button-parent";	
	}
}

Add a click event to all buttons. Remove that event from a certain button.

LDOM

var activateButtonEventId = $("button").on("click", function() {
	this.addClass("button-active");	
});
$("button").eq(1).off(activateButtonEventId);

Vanilla JavaScript

var buttons = document.querySelectorAll("button");
for (var i = 0; i < buttons.length; i++) {
	buttons[i].addEventListener("click", addButtonActiveClass);
}
buttons[1].removeEventListener("click", addButtonActiveClass);

function addButtonActiveClass(){
	if (buttons[i].className.split(" ").indexOf("button-active") === -1) {
		buttons[i].className += " " + "button-active";	
	}
}

Create a text element and insert it after each button.

LDOM

$("<text>")
	.css("text-align", "center")
	.text("Click the button above!")
	.insertAfter($("button"));

Vanilla JavaScript

var textElem = document.createElement("text");
textElem.style.textAlign = "center";
textElem.innerText = "Click the button above!";
var buttons = document.querySelectorAll("button");
for (var i = 0; i < buttons.length; i++) {
	buttons[i].parentNode.insertBefore(textElem.cloneNode(true), buttons[i].nextSibling);
}

The side menu on this page was even generated with the following code!

LDOM

var nav = $("nav");
$("section").each(function () {
	var header = this.find(".section-title").first();
	nav.appendChild(
		$("<a>")
			.addClass("nav-link")
			.prop("href", "#" + header.attr("id"))
			.text(header.text())
	);
});

Vanilla JavaScript

var nav = document.querySelector("nav");
var sections = document.querySelectorAll("section");
for (var i = 0; i < sections.length; i++) {
	var header = sections[i].querySelector(".section-title");
	var a = document.createElement("a");
	a.className = "nav-link";
	a.href = "#" + header.id;
	a.innerText = header.innerText;
	nav.appendChild(a);
}

As you can see, LDOM is an extremely powerful DOM manipulation tool.

$(...)

$(selector)

Parameters

selector
A string containing a selector to match elements against.

Return Value

LDOM Object
An object on which functions can be executed on the element(s) it contains.

Examples

$("button")
$(".section-title")
$("a[href='index.html']")
$(DOMElement)

Parameters

DOMElement
A reference to one or more vanilla DOM Elements.

Return Value

LDOM Object
An object on which functions can be executed on the element(s) it contains.

Examples

$(document.getElementById("#title"))
$(document.querySelectorAll("button"))
$(htmlTag)
Used to create a new HTML element.

Parameters

htmlTag
An HTML opening tag with angled brackets.

Return Value

LDOM Object
An object on which functions can be executed on the element(s) it contains.

Examples

$("<button>")
$("<br>")

.each()

.each(function)

Parameters

function
A function(index) which gets called on for each element of the LDOM Object. this refers to an LDOM Object for the current element. You can optionally return false; from the function to break out of the loop early.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").each(function(){
	console.log(this.get(0));
});
$("p").each(function(i){
	this.text("Paragraph #" + i);
});
.each(function, reverse)

Parameters

function
A function(index) which gets called on for each element of the LDOM Object. this refers to an LDOM Object for the current element. You can optionally return false; from the function to break out of the loop early.
reverse
If true, then the elements will be looped through in reverse order.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").each(function(){
	console.log(this.get(0));
}, true);

.equals()

.equals(LDOMObject)

Parameters

LDOMObject
A LDOM Object to compare against the calling LDOM Object.

Return Value

Boolean
True if both LDOM Objects contain the same elements. False if not.

Information

Although the element order will affect the equality comparison, in most situations this will not make a difference.

Examples

$("div").children().filter("h1").equals($("div>h1"))

.find()

.find(selector)

Parameters

selector
A string containing a selector to match elements against. Searches the DOM tree from the current LDOM Object's Elements.

Return Value

LDOM Object
A new LDOM Object containing the selected elements.

Examples

$("section").find("h3")
$("p").find(".alert-text")

.parent()

.parent()

Return Value

LDOM Object
A new LDOM Object containing the parent of each element.

Examples

$("p").parent()

.children()

.children()

Return Value

LDOM Object
A new LDOM Object containing the children of each element.

Examples

$("p").children()

.filter()

.filter(selector)

Parameters

selector
A string containing a selector to match the LDOM Object's Elements against.

Return Value

LDOM Object
A new LDOM Object containing the matching elements.

Examples

$("div").children().filter("p")

.first()

.first()

Return Value

LDOM Object
A new LDOM Object containing only the first element.

Examples

$("p").first()

.last()

.last()

Return Value

LDOM Object
A new LDOM Object containing only the last element.

Examples

$("p").last()

.eq()

.eq(index)

Parameters

index
The index of the LDOM Element you wish to retrieve. Negative indexes count from the end of the list.

Return Value

LDOM Object
A new LDOM Object containing only the first element.

Examples

$(".header-title").eq(3)
$(".header-title").eq(-1)

.get()

.get()

Return Value

DOM Element Array
An array of vanilla DOM Elements from the LDOM Object.

Examples

$("button").get()
.get(index)

Parameters

index
The index of the LDOM Element you wish to retrieve. Negative indexes count from the end of the list.

Return Value

DOM Element
A single vanilla DOM Element from the LDOM Object specified by the index.

Information

Will return null if there is no element at the specified index.

Examples

$(".header-title").get(3)
$(".header-title").get(-1)

.on()

.on(eventName, handler)

Parameters

eventName
The event type you want to listen for.
handler
The function to be executed when the event is triggered. this refers to an LDOM Object for the element that triggered the event.

Return Value

eventId
A number representing the event that was added. Can be used to remove that event with off.

Examples

var buttonClickEventId = $("button").on("click", function(){
	this.addClass("activated");
});
$("a").on("customEvent", function(){
	console.log("Custom Event Triggered", this);
});
$("h3").on("click", changeColor);
function changeColor() {
	this.css("color", "#FF0000");
}

.off()

.off()
Removes all event handlers added with .on().

Return Value

undefined
There is no return value.

Examples

$("a").off();
.off(eventName)

Parameters

eventName
The event type you want to remove all handlers for.

Return Value

undefined
There is no return value.

Examples

$("a").off("customEvent");
.off(eventId)

Parameters

eventId
The ID returned from .on() of the event to remove.

Return Value

undefined
There is no return value.

Examples

$("button").off(buttonClickEventId);

.trigger()

.trigger(eventName)

Parameters

eventName
The event type to send.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").trigger("click");
$("a").trigger("customEvent");
.trigger(eventName, data)

Parameters

eventName
The event type to send.
data
An object of data to attach to the event.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").trigger("click", { x: 10, y: 25 });
$("a").trigger("customEvent", { arr: [1, 5, 10] });

.hide()

.hide()
Hides the elements and stores their previous display style. Style can be restored with .show().

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").hide();

.show()

.show()
Returns the elements to the display style that they had before .hide() was called.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").show();

.toggle()

.toggle()
Will show the matching elements if it's hidden or hide if it's visible.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").toggle();
.toggle(show)

Parameters

show
If true, elements will be shown regardless of current state. If false, elements will be hidden regardless of current state.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$(".title").toggle(true);

.css()

.css(property)

Parameters

property
Name of the CSS property to get.

Return Value

String
The computed value of the element's style.

Information

If the LDOM Object contains multiple elements, this will only return the value of the first element. Use .eq(), .first() or .last() to reduce to one element.

Examples

$("button").css("font-size");
$("button").last().css("font-size");
$("button").eq(2).css("font-size");
.css(property, value)

Parameters

property
Name of the CSS property to set.
value
The value to set the CSS property to.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").css("font-size", "35px");
.css(property, value, isImportant)

Parameters

property
Name of the CSS property to set.
value
The value to set the CSS property to.
isImportant
If true, the style will be marked with "!important" specificity.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").css("display", "inline-block", true);

.html()

.html()

Return Value

String
The element's inner HTML.

Information

If the LDOM Object contains multiple elements, this will only return the value of the first element. Use .eq(), .first() or .last() to reduce to one element.

Examples

$("button").html();
$("button").last().html();
$("button").eq(2).html();
.html(htmlString)

Parameters

htmlString
String containing the HTML content to set.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").html("<a href='index'>Home</a>");

.outerHTML()

.outerHTML()

Return Value

String
The element's outer HTML.

Information

If the LDOM Object contains multiple elements, this will only return the value of the first element. Use .eq(), .first() or .last() to reduce to one element.

Examples

$("button").outerHTML();
$("button").last().outerHTML();
$("button").eq(2).outerHTML();
.outerHTML(htmlString)

Parameters

htmlString
String containing the outer HTML to set.

Return Value

undefined
There is no return value.

Information

Outer HTML replaces the entire element; therefore will break event listeners and any LDOM Objects that had reference to that element. It's not recommend to set outer HTML if you can help it.

Examples

$("a").outerHTML("<button>I'm now a button!</button>");

.text()

.text()

Return Value

String
The element's text.

Information

If the LDOM Object contains multiple elements, this will only return the value of the first element. Use .eq(), .first() or .last() to reduce to one element.

Examples

$("button").text();
$("button").last().text();
$("button").eq(2).text();
.text(textString)

Parameters

textString
String containing the text content to set.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").text("Click me!");

.prop()

.prop(propertyName)

Parameters

propertyName
Name of the HTML property to get.

Return Value

String
The element's HTML property value.

Information

If the LDOM Object contains multiple elements, this will only return the value of the first element. Use .eq(), .first() or .last() to reduce to one element.

Examples

$("input").prop("readOnly");
$("input").last().prop("value");
$("input").eq(2).prop("required");
.prop(propertyName, value)

Parameters

propertyName
Name of the HTML property to set.
value
String containing the property value to set.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("input").prop("readOnly", "true");
$("input").prop("value", "Enter Phone Number");

Attr vs Prop

Often times .attr() and .prop() can be used interchangeably. In general, .attr() should be used to get/set the value as literally written in the HTML document. .prop() should be used to get/set the computed value as seen by JavaScript's DOM tree.

.attr()

.attr(attributeName)

Parameters

attributeName
Name of the HTML attribute to get.

Return Value

String
The element's HTML attribute value.

Information

If the LDOM Object contains multiple elements, this will only return the value of the first element. Use .eq(), .first() or .last() to reduce to one element.

Examples

$("input").attr("aria-label");
$("input").last().attr("title");
$("input").eq(2).attr("data-meta");
.attr(attributeName, value)

Parameters

attributeName
Name of the HTML attribute to set.
value
String containing the attribute value to set.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").attr("title", "You can click me!");

Attr vs Prop

Often times .attr() and .prop() can be used interchangeably. In general, .attr() should be used to get/set the value as literally written in the HTML document. .prop() should be used to get/set the computed value as seen by JavaScript's DOM tree.

.removeAttr()

.removeAttr(attributeName)

Parameters

attributeName
Name of the HTML attribute to remove.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").removeAttr("disabled");

.addClass()

.addClass(className)

Parameters

className
String containing one or more space-separated classes to be added.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").addClass("large-button");
$("button").addClass("large-button button-warning");

.removeClass()

.removeClass()
Will remove all classes from the matching elements.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").removeClass("large-button");
$("button").removeClass("large-button button-warning");
.removeClass(className)

Parameters

className
String containing one or more space-separated classes to be removed.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("button").removeClass("large-button");
$("button").removeClass("large-button button-warning");

.hasClass()

.hasClass(className)

Parameters

className
String containing one class name to search for.

Return Value

Boolean
True if any LDOM Object Element has the class. False if all elements do not.

Examples

$("button").hasClass("large-button");
.hasClass(className, all)

Parameters

className
String containing one class name to search for.
all
If true, this function will return true only if all elements have the class.

Return Value

Boolean
True if all LDOM Object Elements have the class. False if at least one does not.

Examples

$("button").hasClass("large-button", true);

.insertAfter()

.insertAfter(targetElement)

Parameters

targetElement
A LDOM Object for which all of the calling LDOM Elements will be cloned and inserted after.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("<a>").text("Click Me").insertAfter($("img"));

.insertBefore()

.insertBefore(targetElement)

Parameters

targetElement
A LDOM Object for which all of the calling LDOM Elements will be cloned and inserted before.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("<a>").text("Click Me").insertBefore($("img"));

.appendChild()

.appendChild(childElement)

Parameters

childElement
A LDOM Object which will be cloned and appended to all of the calling LDOM Elements.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("h3").appendChild($("<img>").attr("src", "banner.png"));

.prependChild()

.prependChild(childElement)

Parameters

childElement
A LDOM Object which will be cloned and prepended to all of the calling LDOM Elements.

Return Value

LDOM Object
The existing LDOM Object is returned to allow function chaining.

Examples

$("section").prependChild($("table"));

.remove()

.remove()
Will remove the calling LDOM Elements from the DOM.

Return Value

undefined
There is no return value.

Examples

$("button").remove();

.length

.length

Value

Number
The number of LDOM Elements in the LDOM Object.

Examples

$("section").length
$("p").children().length