# dom-elementals

> Easy DOM creation, and identity

Latest version **1.0.1** (published 2017-09-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install dom-elementals
pnpm add dom-elementals
yarn add dom-elementals
bun add dom-elementals
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2017-09-10 |
| First published | 2017-09-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 6 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Quentin Engles |
| Maintainers | hollowdoor |
| Keywords | DOM, creation, manipulation, string |

## Links

- npm: https://www.npmjs.com/package/dom-elementals
- npm.io page: https://npm.io/package/dom-elementals

## Dependencies (6)

- [is-dom](https://npm.io/package/is-dom.md) ^1.0.9
- [isobject](https://npm.io/package/isobject.md) ^3.0.1
- [camelcase](https://npm.io/package/camelcase.md) ^4.1.0
- [array-from](https://npm.io/package/array-from.md) ^2.1.1
- [decamelize](https://npm.io/package/decamelize.md) ^1.2.0
- [is-array-like](https://npm.io/package/is-array-like.md) ^1.1.2

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.0.1 (latest) — 2017-09-10
- 1.0.0 — 2017-09-07

## README

dom-elementals
=============

Install
------

`npm install --save dom-elementals`

About
----

It's kind of complicated. Let's say it's about making some certain things easier when it comes to browser DOM.

toElement()
-----------

```javascript
import { toElement } from 'dom-elementals';
```

`toElement` is the most important thing. It has an extremely overloaded API.

### toElement(selector) -> selected element

Simply select a single element from the DOM. This is equivalent to `document.querySelector()`.

### toElement(html string) -> new element

Create a DOM element, or DOM DocumentFragment from an html string.

If there are multiple elements in the top level `toElement()` returns a DocumentFragment. If there is one top level element `toElement()` will return the DOM element version of that.


### toElement(element|fragment) -> element|fragment

If you pass an element, or a DocumentFragment to `toElement()` you get it back unaltered. This is for composability purposes.

### toElement(array) -> fragment

**Warning: Infinite circular recursion possible.**

Pass an array to `toElement()`, and it will iterate over that array making elements out of the array values. All array values can be something `toElement()` accepts. All new elements are combined into a DocumentFragment.


### toElement(object) -> new element

**Warning: Infinite circular recursion possible.**

Pass an object with an `element` property. That element property will be turned into the element returned by `toElement()`.

Or pass an object like this:

```javascript
//Create an element
let element = toElement({
    //The tag property is the only required property
    //Here we create a paragraph element
    //tag is equivalent to element.tagName.toLowerCase()
    "tag": "p",
    //Properties in general are set on element
    //All properties that belong to DOM elements are acceptable
    "id": "first-name",
    "textContent": "Tabitha",
    "className": "paragraph-name",
    //Add attributes
    //Just like element.setAttribute(name, value)
    "attributes": {

    },
    //These children will be appended to the element
    "children": [
        //toElement(children[index]) will convert each child
    ],
    //Set element.dataset values
    //To set data-* attributes you might need a polyfill
    "data": {
        "value": 1,
        //Use camelcase, or dash case
        "other-value": 2,
        "camelValue": 3
    },
    //The parent to append element to.
    //This is passed to toElement() as well.
    "parent": "#parent-id-selector",
    //Set the first html of the element
    "head": "<h2>I'm set before anything else</h2>",
    //Set the last html of the element
    "foot": "<footer>I'm set after everything else</footer>",
    //Set styles
    "style": {
        "color": "blue"
    }
});
```

Create a simple input while setting the value.

```javascript
let input = toElement({
    tag: 'input',
    value: "I'm a value"
});
```

### toElement(strings, ...values) -> new element

This is an interface to template literals. All `values` are converted to javascript primitive values (string, number, ...)--even the elements.

You can use it directly:

```javascript
let value = 'Hello Universe!';
let element = toElement`<p>${value}</p>`;
```

Or indirectly:

```javascript
function createElement(strings, ...values){
    return toElement(strings, ...values);
}
let value = 'Hello Cosmos!';
let element = createElement`<p>${value}</p>`;
```

toHTML()
-------

```javascript
import { toHTML } from 'dom-elementals';
```

`toHTML(value)` can except these values:

* DOM element
* object with an element property
* DocumentFragment

arrayFrom()
---------

`arrayFrom(arrayLike)` is not really a DOM specific thing, but conversion of array like objects is so common it is included.

setAttributes()
---------

`setAttributes(element, object)` is used to set all the attributes of a given `object` on to the `element`.

isElement()
---------

`isElement(value)` returns true if `value` is an element.

---
_Source: https://npm.io/package/dom-elementals · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._