create-elms
Create HTML elements, set attributes, add to other elements, and return an array of DOM nodes or HTML markup in a single function call.
Features
- Create elements using strings or objects
- 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
Installation
NPM:
npm install create-elms
// file.js;const elms = ;
Git:
git clone https://github.com/jhildenbiddle/create-elms.git
CDN (jsdelivr.com shown, also on unpkg.com):
<!-- ES5 (latest v1.x.x) -->
<!-- ES6 module (latest v1.x.x) -->
Examples
Render elements using strings and/or objects:
let elm elms; // Create an element from a stringelm = ; // => [elm] // ... or an objectelm = ; // => [elm] // ... or multiple elements from a stringelms = ; // => [elm, elm, elm] // ... or an array of stringselms = ; // => [elm, elm, elm] // ... or an array of objectselms = ; // => [elm, elm, elm] // ... or an array containing strings and objectselms = ; // => [elm, elm, elm]
Set per-element attributes or shared attributes:
let elm elms; // Set attributes on specific elements...elm = ; // ... or use the 'sharedOptions' argument for multiple elementData objectselms = ; // ... or to apply options to one-or-more elementData stringselms = ;
Append, prepend, or insert elements:
let elm elms; // Use CSS selectors, HTMLElement(s) or Node(s)elm = ;elm = ;elm = ;elm = ; // ... or an array of CSS selectors, HTMLElements, and/or Nodeselm = ; // Specify multiple append/prepend/insert points per elementelms = ; // ... or use the 'shadedOptions' argument for multiple elementselms = ;
Have elements returned as HTMLElements or HTML markup:
// Return as HTML elements (default)let elm = ;// => [elm] // Return as HTML markuplet html = ;// => '<p></p>'
Usage
- Returns:
Array
- An array of of elements (default)
- An array of HTML markup (when returnHtml option is
true
).
elementData
- Type:
Object
,String
, orArray
String
should be valid HTML markupObject
should be an HTMLElement or NodeArray
should 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
String
elementData - If sharedOptions are used, options will be applied to all top-level elements in the string
Objects
- The
html
value will be inserted as HTML content - The
text
value will be inserted as text content. This value is ignored ifhtml
is defined. - The
attr
value should contain attribute name/value pairs - The
appendTo
,prependTo
,insertBefore
andinsertAfter
properties accept a CSS selector, HTMLElement, HTMLCollection, Node, NodeList, or anArray
of theseObject
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
// Stringlet elm1 = ;// => [elm] (top-level <p> is returned, not nested <a>) // String with multiple elementslet elms1 = ;// => [elm, elm, elm] (all top-level elements returned) // Objectlet elm2 = ;// => [elm] // Array of strings and/or objectslet elms = ;// => [elm, elm]
sharedOptions
- 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
, thetag
property 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 markuplet html = ;// => '<p>Text</p>'
documentObject
- 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 = ;const jsdom = ;const dom = ;const jsDocument = domwindowdocument; let elm =
Contact
- Create a Github issue for bug reports, feature requests, or questions
- Follow @jhildenbiddle for announcements
- Add a ⭐️ star on GitHub or ❤️ tweet to support the project!
License
This project is licensed under the MIT License. See the LICENSE for details.
Copyright (c) John Hildenbiddle (@jhildenbiddle)