Create HTML elements, set attributes, add to other elements, and return an array of DOM nodes or HTML markup in a single function call.
- Quickly create HTML elements using markup or JavaScript objects
- Set attributes on individual or groups of elements
- Append, prepend, and insert elements before or after other elements
- Return an array of elements or HTML markup
- UMD and ES6 module available
- Compatible with modern and legacy browsers (IE9+)
- Compatible with Node environments using jsdom
- Lightweight (~1k min+gzip) and dependency-free
NPM:
npm install create-elms// file.js
import createElms from 'create-elms';
const elms = createElms(/* ... */);Git:
git clone https://github.com/jhildenbiddle/create-elms.gitCDN (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)- Returns:
Array- An array of of elements (default)
- An array of HTML markup (when returnHtml option is
true).
- Type:
Object,String, orArrayStringshould be valid HTML markupObjectshould be an HTMLElement or NodeArrayshould contain HTML markup, HTMLElements, and/or Nodes
Strings
- Strings may contain multiple elements
- Each top-level element in a string will be returned in the return
Array - Use sharedOptions to apply properties to
StringelementData - If sharedOptions are used, options will be applied to all top-level elements in the string
Objects
- The
htmlvalue will be inserted as HTML content - The
textvalue will be inserted as text content. This value is ignored ifhtmlis defined. - The
attrvalue should contain attribute name/value pairs - The
appendTo,prependTo,insertBeforeandinsertAfterproperties accept a CSS selector, HTMLElement, HTMLCollection, Node, NodeList, or anArrayof theseObjecttypes.
| 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]- Type:
Object - Default:
{}
Options are applied to all elementData with the following rules:
- When applied to an elementData
Object, all options are valid. - When applied to an elementData
String, thetagproperty is ignored. - Existing tags, attributes, HTML and text content will not be replaced by shared options.
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>'- Type:
Object - Default:
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! 🙏🏻
- Follow 👨🏻💻 @jhildenbiddle on Twitter and GitHub for announcements
- Create a 💬 GitHub issue for bug reports, feature requests, or questions
- Add a ⭐️ star on GitHub and 🐦 tweet to promote the project
- Become a 💖 sponsor to support the project and future efforts
This project is licensed under the MIT License. See the LICENSE for details.
Copyright (c) John Hildenbiddle (@jhildenbiddle)