A lightning fast dom query and manipulation lib for when speed matters.
Documentation
- about
- installation
- build
- performance
- API
- id
- class
- tag
- qs
- qsa
- name
- addClass
- rmClass
- tgClass
- hasClass
- attr
- rmAttr
- tgAttr
- getAttr
- child
- parent
- after
- before
- first
- last
- clone
- append
- prepend
- next
- prev
- rm
- empty
- replace
- html
- txt
- each
- filter
- on
- off
- addEvt
- rmEvt
- css
- eq
- click
- submit
- focus
- blur
- cb
- set
- create
about
Domscript is a lightning fast dom query/manipulation tool that you can easily customize to suit your needs.
The goal of domscript is to enable developers to rapidly chain methods while achieving similar to vanilla js speed.
if you can query and manipulate the dom with javascript, you can already use domscript.
you should get the same results and errors as though you were writting vanilla js.
- all prototype methods are optional
- custom methods can be easily be built into the prototype chain
- current maximum build size of 3.1kb minified
- no regex/unsafe functions
- about as close to using vanilla js speed as it gets.
installation
npm
stable release
$ npm install @angeal185/domscript --save
dev release
git
$ git clone https://github.com/angeal185/domscript.git
browser
<html>
<head>
<meta charset="utf-8">
<script src="/path/to/domscript.mjs" type="module"></script>
<!-- or -->
<script src="/path/to/domscript.js"></script>
</head>
</html>
build
$ npm run build
will build domscript into the ./dist
folder.
- the config file is located at
./build/config.json
. - the build source is located at
./lib/index.js
. config.includes
allows you to enable/disable prototype methods from the final build.- You can also reorganize the order of the prototype chain based on your usage of the methods
- reorganization should be done with your most used methods at the top.
- you can also manually add custom methods to the prototype at
./lib/index.js
. - the custom method names should be added and enabled to
config.includes
config.export_as
controls the variable name used to call domscript.config.module_name
controls the built output base name.config.module_ext
controls the built output file extension.config.iuclude_utils
controls adding the util function.- if none of your methods use domscripts util function
config.iuclude_utils
will exclude it from the build. config.is_module
controls the export method of domscript.- if you are not using domscript as a module,
config.is_module
should befalse
performance
below is a very basic example of domscripts potential.
// jquery
console.time('jquery')
for (let i = 0; i < 1000; i++) {
$('#test-id').addClass('test1').text('test1');
}
console.timeEnd('jquery');
// zepto
console.time('zepto')
for (let i = 0; i < 1000; i++) {
$('#test-id').addClass('test2').text('test2');
}
console.timeEnd('zepto');
// umbrella.js
console.time('umbrella')
for (let i = 0; i < 1000; i++) {
u('#test-id').addClass('test3').text('test3');
}
console.timeEnd('umbrella');
// vanilla javascript
console.time('javascript')
for (let i = 0; i < 1000; i++) {
let item = document.getElementById('test-id');
item.classList.add('test4');
item.textContent = 'test4';
}
console.timeEnd('javascript');
// domscript
console.time('domscript')
for (let i = 0; i < 1000; i++) {
d.id('test-id').addClass('test5').txt('test5');
}
console.timeEnd('domscript');
// jquery 157.0546875ms
// zepto 145.590087890625ms
// umbrella 143.53515625ms
// javascript 14.052001953125ms
// domscript 18.84423828125ms
your end results should always have domscript running similar speed to native js. the lower the amount of methods included in the domscript prototype, the faster and closer it should be. if you don't use it, exclude it.
id
get elementById
examples:
// return element by id
d.id('test-id').r;
// get element by id, add class
d.id('test-id').addClass('test-class');
// get element by id, add class, add onclick event
d.id('test-id').addClass('test-class').on('click', function(evt){
console.log(evt.target.id)
});
class
get elementsByClassName
examples:
// return HTMLCollection by class
d.class('test-class').r;
// return element by class and index
d.class('test-class', 0).r;
// get HTMLCollection by class, add id to each
d.class('test-class').each(function(ele, idx){
ele.id = 'id-'+ idx
});
// get first element by class, add id
d.class('test-class', 0).id('test-id');
tag
get elementsByTagName
examples:
// return HTMLCollection by tag
d.tag('div').r;
// return element by tag and index
d.tag('div', 0).r;
// get HTMLCollection by tag, add id to each
d.tag('div').each(function(ele, idx){
ele.id = 'id-'+ idx
});
// get first element by tag, add id
d.tag('tag', 0).id('test-id');
qs
document querySelector
examples:
// return element by selector
d.qs('#test-id p').r;
// remove element by selector
d.qs('#test-id p').rm();
// get element by selector and return textContent
d.qs('#test-id p').txt();
// get element by selector and edit textContent
d.qs('#test-id p').txt('new text');
// get element by selector and edit style
d.qs('#test-id p').css('color', 'red');
qsa
document querySelectorAll
examples:
// return HTMLCollection by selector
d.qsa('.test-class p');
// get elements by selector and edit textContent of each
d.qsa('.test-class p').each(function(ele,idx){
ele.textContent = 'element '+ idx;
})
// get element by selector and remove all
d.qsa('.test-class p').each(function(ele, idx){
ele.remove()
});
name
get elementsByName
examples:
// return HTMLCollection by name
d.name('test-name').r;
// return element by name and index
d.name('test-name', 0).r;
// get HTMLCollection by name, add id to each
d.name('test-name').each(function(ele, idx){
ele.id = 'id-'+ idx
});
// get first element by name, add id
d.name('test-name', 0).id('test-id');
addClass
add class/classlist to element
examples:
// add a class
d.id('test-id').addClass('class1');
// add classes
d.id('test-id').addClass('class1','class2','class3');
rmClass
remove class/classlist to element
examples:
// remove a class
d.id('test-id').rmClass('class1');
// remove classes
d.id('test-id').rmClass('class1','class2','class3');
tgClass
toggle class of element
examples:
// remove/add class
d.id('test-id').tgClass('class1');
hasClass
check if class exists
examples:
// check if class exists
if(d.id('test-id').hasClass('class1')){
console.log('class1 exists!')
} else {
console.log('class1 does not exist!')
}
attr
set attribute/s
examples:
// add an attribute
d.id('some-input').attr('type', 'text');
// add multiple attributes
d.id('some-input').attr({
type: 'text',
placeHolder: 'some placeholder'
});
rmAttr
remove attribute/s
examples:
// remove an attribute
d.id('some-input').rmAttr('type');
// remove multiple attributes
d.id('some-input').rmAttr('type', 'placeHolder');
tgAttr
toggle attribute/s
examples:
// add/remove an attribute
d.id('some-input').tgAttr('readonly');
// force add/remove an attribute
d.id('some-input').tgAttr('readonly', true);
getAttr
get an element attribute/s
examples:
// get an attribute
console.log(
d.id('some-input').getAttr('placeHolder')
)
// 'some placeholder'
// get multiple attributes
console.log(
d.id('some-input').getAttr(['type', 'placeHolder'])
)
//{type:"text",placeHolder:"some placeholder"}
child
get an element child/ren
examples:
// return HTMLCollection of children
d.id('test-id').child().r
// get children HTMLCollection and add id to each
d.id('test-id').child().each(function(ele, idx){
ele.id = 'id-'+ idx
});
// return child element by index
d.id('test-id').child(0).r
// return child element by index and return textContent
d.id('test-id').child(0).txt()
// return child element by index and edit textContent
d.id('test-id').child(0).txt('new text')
parent
get an elements parent element
examples:
// return element parent
d.id('test-id').parent().r
// edit element parent textContent
d.id('test-id').parent().txt('i am the parent')
// return element parent's textContent
d.id('test-id').parent().txt()
// remove all children of parent
d.id('test-id').parent().empty()
// remove parent
d.id('test-id').parent().rm()
after
insert after element
examples:
let item = d.create('div').r;
// insert elements and text after querySelected element
d.id('test-id')
.after(item.cloneNode(),item.cloneNode(), 'after')
.before(item.cloneNode(),item.cloneNode(), 'before')
before
insert before element
examples:
let item = d.create('div').r;
// insert elements and text before querySelected element
d.qs('#test-id')
.before(item.cloneNode(),item.cloneNode(), 'before')
.after(item.cloneNode(),item.cloneNode(), 'after')
first
get elements first child
examples:
// get firstChild of element
d.id('test-id').first().r
// remove firstChild of element
d.id('test-id').first().rm()
// empty firstChild of element
d.id('test-id').first().empty()
last
get elements last child
examples:
// get lastChild of element
d.id('test-id').last().r
// remove lastChild of element
d.id('test-id').last().rm()
// empty lastChild of element
d.id('test-id').last().empty()
clone
clone an element
examples:
// return a clone of selected element
d.id('test-id').clone().r
// return a deep clone of selected element
d.id('test-id').clone(true).r
append
append to an element
examples:
let item = d.create('div').r;
// append elements and text to querySelected element
d.qs('#test-id')
.append(item.cloneNode(),item.cloneNode(), 'appended')
.prepend(item.cloneNode(),item.cloneNode(), 'prepended')
prepend
prepend to an element
examples:
let item = d.create('div').r;
// prepend elements and text to querySelected element
d.qs('#test-id')
.prepend(item.cloneNode(),item.cloneNode(), 'prepended')
.append(item.cloneNode(),item.cloneNode(), 'appended')
next
next sibling
examples:
// return the direct nextSibling
d.id('test-id').next().r
// return the nextElementSibling
d.id('test-id').next(true).r
// or d.id('test-id').next(1).r
// change textContent of nextElementSibling
d.id('test-id').next(true).txt('ok')
// get textContent of nextElementSibling
d.id('test-id').next(true).txt()
// return a clone of the nextElementSibling
d.id('test-id').next(true).clone().r
prev
previous sibling
examples:
// return the direct previousSibling
d.id('test-id').prev().r
// return the previousElementSibling
d.id('test-id').prev(true).r
// or d.id('test-id').prev(1).r
// change textContent of previousElementSibling
d.id('test-id').prev(true).txt('ok')
// get textContent of previousElementSibling
d.id('test-id').prev(true).txt()
// return a clone of the previousElementSibling
d.id('test-id').prev(true).clone().r
rm
remove element
examples:
// remove selected element
d.id('test-id').rm();
// remove selected elements firstchild
d.id('test-id').first().rm();
empty
empty element
examples:
// remove all childnodes from selected element ~ loop
d.id('test-id').empty();
// remove all childnodes from selected element ~ innerHTML = ''
d.id('test-id').empty(true);
// or d.id('test-id').empty(1);
// remove all childnodes from selected elements lastchild
d.id('test-id').last().empty();
replace
replace element
examples:
let item = d.create('div').attr('id', 'replaced').r;
// replace an element with another element
d.id('test-id').replace(item)
// replace an element with another element and edit new element
d.id('test-id').replace(item).txt('replace success')
html
add or return innerHTML
examples:
// return innerHTML of element
d.id('test-id').html()
// replace or add innerHTML of element
d.id('test-id').html('<p>new innerHTML</p>');
txt
add or return textContent
examples:
// return textContent of element
d.id('test-id').txt()
// replace or add textContent of element
d.id('test-id').txt('new text');
each
loop over elements examples:
// get HTMLCollection by class, add id to each
d.class('test-class').each(function(ele, idx){
ele.id = 'id-'+ idx
});
d.qsa('.test-class p').each(function(ele,idx){
ele.textContent = 'element '+ idx;
})
// get element by selector and remove all
d.qsa('.test-class p').each(function(ele, idx){
ele.remove()
});
filter
return filtered items
examples:
// filter HTMLCollection
d.class('class1').filter(function(ele, idx){
return ele.id !== 'id3';
}).each(function(ele, idx){
ele.textContent = 'ok';
})
d.class('class1').filter(function(ele, idx){
return ele.id !== 'id3';
}).r[0]
on
attach single on* event to element
examples:
// get element by id and add onclick event
d.id('test-id').on('click', function(evt){
console.log(evt.target)
});
// get element by id and add onkeyup event
d.id('test-input').on('keyup', function(evt){
console.log(evt.target)
});
// get element by id and add onload event
d.id('test-img').on('load', function(evt){
console.log(evt.target)
});
off
remove single on* event from element
examples:
// get element by id and remove onclick event
d.id('test-id').off('click');
// get element by id and remove onkeyup event
d.id('test-input').off('keyup');
// get element by id and remove onload event
d.id('test-img').off('load');
addEvt
attach event listener to element
examples:
function clickEvt(){
console.log('clicked')
}
function keyEvt(){
console.log('keyup')
}
function loadEvt(){
console.log('loaded')
}
// get element by id and add click event listener
d.id('test-id').addEvt('click', clickEvt);
// get element by id and add onkeyup event
d.id('test-input').addEvt('keyup', keyEvt);
// get element by id and add onload event
d.id('test-img').addEvt('load', loadEvt);
rmEvt
remove event listener from element
examples:
function clickEvt(){
console.log('clicked')
}
function keyEvt(){
console.log('keyup')
}
function loadEvt(){
console.log('loaded')
}
// get element by id and remove click event listener
d.id('test-id').rmEvt('click', clickEvt);
// get element by id and remove onkeyup event
d.id('test-input').rmEvt('keyup', keyEvt);
// get element by id and remove onload event
d.id('test-img').rmEvt('load', loadEvt);
css
add styles to element
examples:
// get element by selector and add single style
d.id('test-id').css('color', 'red');
// get element by selector and add multiple styles
d.id('test-id').css({
'color': 'red',
'font-size': '96px'
});
eq
select element by index
examples:
d.class('test-class', 0).txt('index 0')
// or
d.class('test-class').eq(1).txt('index 1')
click
click an element
examples:
// get element by selector and add single style
d.id('some-button').click();
submit
submit a form
examples:
// get element by selector and add single style
d.id('some-form').submit();
focus
focus an element
examples:
//focus an element
d.id('some-input').focus();
d.id('some-input').focus().attr('type','text');
d.id('some-input').attr({
placeHolder: 'test focus',
type: 'text'
}).focus()
d.id('some-input').on('focus', function(evt){
console.log('focus event')
}).focus();
blur
blur an element
examples:
//blur a focused element
d.id('some-input').focus();
d.id('some-input').on('blur', function(evt){
console.log('blur event')
}).focus().blur();
cb
add callback to an item containing current proto state
examples:
// return element within callback function
d.id('some-element').cb(function(ele){
if(ele){
d.set(ele).attr('readonly', true)
}
})
set
set the current proto state
examples:
// cached reference
let cached_item = d.id('some-input').r,
cached_item2 = d.id('other-input').r;
d.set(cached_item).attr('readonly', true)
d.set(cached_item2).attr('readonly', true)
create
domscript was designed for query/manipulation. It has a basic create function but domscript's sister lib clonecript is a much better alternative and designed to work alongside domscript.
clonescript was made for creation and not query/manipulation clonescript
examples:
let item = d.create('div')
// get element by selector and add created div
d.id('test-id').append(item);
// do not add a proto within the proto
//d.id('test-id').append(d.create('div'));