A micro-library for efficiently creating HTML elements, settings attributes, adding to other elements, and returning an array of elements or HTML markup
MIT License
Create HTML elements, set attributes, add to other elements, and return an array of DOM nodes or HTML markup in a single function call.
NPM:
npm install create-elms
// file.js
import createElms from 'create-elms';
const elms = createElms(/* ... */);
Git:
git clone https://github.com/jhildenbiddle/create-elms.git
CDN (jsdelivr.com shown, also on unpkg.com):
<!-- ES5 (latest v1.x.x) -->
<script src="https://cdn.jsdelivr.net/npm/create-elms@1"></script>
<script>
var elms = createElms(/* ... */);
</script>
<!-- ES6 module (latest v1.x.x) -->
<script type="module">
import getCssData from 'https://cdn.jsdelivr.net/npm/create-elms@1/dist/create-elms.esm.min.js';
const elms = createElms(/* ... */);
</script>
Render elements using strings and/or objects:
let elm, elms;
// Create an element from a string
elm = createElms('<p>Foo</p>'); // => [elm]
// ... or an object
elm = createElms({
tag : 'p',
text: 'Foo'
}); // => [elm]
// ... or multiple elements from a string
elms = createElms('<p>Foo</p><p>Bar</p><p>Baz</p>'); // => [elm, elm, elm]
// ... or an array of strings
elms = createElms([
'<p>Foo</p>',
'<p>Bar</p>',
'<p>Baz</p>'
]); // => [elm, elm, elm]
// ... or an array of objects
elms = createElms([
{ tag: 'p', text: 'Foo' },
{ tag: 'p', text: 'Bar' },
{ tag: 'p', text: 'Baz' }
]); // => [elm, elm, elm]
// ... or an array containing strings and objects
elms = createElms([
'<p>Foo</p>',
'<p>Bar</p>',
{ tag: 'p', text: 'Baz' }
]); // => [elm, elm, elm]
Set per-element attributes or shared attributes:
let elm, elms;
// Set attributes on specific elements...
elm = createElms({
tag : 'p',
text: 'Foo',
attr: { id: 'foo', class: 'myclass' }
});
// ... or use the 'sharedOptions' argument for multiple elementData objects
elms = createElms(
// elementData
[
{ text: 'Foo', attr: { id: 'foo' } },
{ text: 'Bar', attr: { id: 'bar' } },
{ text: 'Baz', attr: { id: 'baz' } }
],
// sharedOptions
{
tag : 'p',
attr: { class: 'myclass' }
}
);
// ... or to apply options to one-or-more elementData strings
elms = createElms(
// elementData
[
'<p id="foo">Foo</p>',
'<p id="bar">Bar</p>',
'<p id="baz">Baz</p>'
],
// sharedOptions
{
class: 'myclass'
}
);
Append, prepend, or insert elements:
let elm, elms;
// Use CSS selectors, HTMLElement(s) or Node(s)
elm = createElms({ tag: 'p', appendTo: 'body' });
elm = createElms({ tag: 'p', appendTo: document.body });
elm = createElms({ tag: 'p', appendTo: document.querySelector('body') });
elm = createElms({ tag: 'p', appendTo: document.querySelectorAll('div') });
// ... or an array of CSS selectors, HTMLElements, and/or Nodes
elm = createElms({
tag : 'p',
appendTo: [
'body',
document.querySelectorAll('div')
]
});
// Specify multiple append/prepend/insert points per element
elms = createElms({
tag : 'p',
appendTo : 'body',
prependTo : document.body,
insertBefore: document.querySelectorAll('div'),
insertAfter : document.getElementsByTagName('h1')
});
// ... or use the 'shadedOptions' argument for multiple elements
elms = createElms(
// elementData
[
'<p>Text1</p>',
'<p>Text2</p>'
],
// shadedOptions
{
appendTo : 'body',
prependTo : document.body,
insertBefore: document.querySelectorAll('div'),
insertAfter : document.getElementsByTagName('h1')
}
);
Have elements returned as HTMLElements or HTML markup:
// Return as HTML elements (default)
let elm = createElms({ tag: 'p' });
// => [elm]
// Return as HTML markup
let html = createElms({ tag: 'p' }, { returnHtml: true });
// => '<p></p>'
createElements(elementData, sharedOptions = {}, documentObject = window.document)
Array
true
).Object
, String
, or Array
String
should be valid HTML markupObject
should be an HTMLElement or NodeArray
should contain HTML markup, HTMLElements, and/or NodesStrings
Array
String
elementDataObjects
html
value will be inserted as HTML contenttext
value will be inserted as text content. This value is ignored if html
is defined.attr
value should contain attribute name/value pairsappendTo
, prependTo
, insertBefore
and insertAfter
properties accept a CSS selector, HTMLElement, HTMLCollection, Node, NodeList, or an Array
of these Object
types.Property | Type | Description |
---|---|---|
tag | string | Element HTML tag |
attr | object | Element attributes |
html | string | Content to append to element(s) as HTML |
text | string | Content to append to element(s) as text |
appendTo | object|string | Node(s) to append element(s) to |
prependTo | object|string | Node(s) to prepend element(s) to |
insertBefore | object|string | Node(s) to insert element(s) before |
insertAfter | object|string | Node(s) to insert element(s) after |
Examples
// String
let elm1 = createElement('<p id="foo" class="myclass"><a href="/">Home</a>');
// => [elm] (top-level <p> is returned, not nested <a>)
// String with multiple elements
let elms1 = createElement('<p>Text1</p><p>Text2</p><p>Text3</p>');
// => [elm, elm, elm] (all top-level elements returned)
// Object
let elm2 = createElement({
tag : 'p',
html: '<a href="/">Home</a>',
attr: { id: 'foo', class: 'myclass' }
});
// => [elm]
// Array of strings and/or objects
let elms = createElement([
'<p>Text</p>',
{ tag: 'p', text: 'Text' }
]);
// => [elm, elm]
Object
{}
Options are applied to all elementData with the following rules:
Object
, all options are valid.String
, the tag
property is ignored.Object properties
All properties from elementData plus the following:
Property | Type | Default | Description |
---|---|---|---|
returnHtml | Boolean | false |
Return elements as array of HTML markup when true . |
Example
// Return as HTML markup
let html = createElms(
// elementData
{ tag: 'p', text: 'Text' },
// sharedOptions
{ returnHtml: true }
);
// => '<p>Text</p>'
Object
window.document
This is the document object on which document.createElement
and document.querySelectorAll
methods will be called. The default value assumes a browser environment, but passing a reference to a document object created by tools like jsdom allows creating HTML elements and markup in a Node environment (without polluting global variables).
Example
const createElms = require('create-elms');
const jsdom = require('jsdom');
const dom = new JSDOM();
const jsDocument = dom.window.document;
let elm = createElms({ tag: 'p', {}, dom.window.document)
// => [elm]
let html = createElms({ tag: 'p', { returnHtml: true }, dom.window.document)
// => '<p></p>'
A sponsorship is more than just a way to show appreciation for the open-source authors and projects we rely on; it can be the spark that ignites the next big idea, the inspiration to create something new, and the motivation to share so that others may benefit.
If you benefit from this project, please consider lending your support and encouraging future efforts by becoming a sponsor.
Thank you! 🙏🏻
This project is licensed under the MIT License. See the LICENSE for details.
Copyright (c) John Hildenbiddle (@jhildenbiddle)