# element-props

> Normalize access to element attributes/properties

Latest version **2.6.0** (published 2023-04-14) · ISC license · 0 weekly downloads

## Install

```sh
npm install element-props
pnpm add element-props
yarn add element-props
bun add element-props
```

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.6.0 |
| Published | 2023-04-14 |
| First published | 2020-05-28 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 10.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | Dmitry Iv. |
| Maintainers | dy |
| Keywords | element, props, properties, proptypes, spectjs, attr-types, attribute, parse-attributes, attr-type, attributes |

## Links

- npm: https://www.npmjs.com/package/element-props
- Repository: https://github.com/spectjs/element-props
- Homepage: https://github.com/spectjs/element-props#readme
- Issues: https://github.com/spectjs/element-props/issues
- npm.io page: https://npm.io/package/element-props

## Recent versions

- 2.6.0 (latest) — 2023-04-14
- 2.5.1 — 2023-04-02
- 2.5.0 — 2023-04-02
- 2.4.2 — 2022-11-30
- 2.4.1 — 2022-11-30
- 2.4.0 — 2022-11-30
- 2.3.0 — 2022-11-17
- 2.2.1 — 2022-11-16
- 2.2.0 — 2022-11-16
- 2.1.0 — 2022-11-16
- 2.0.4 — 2022-01-19
- 2.0.3 — 2022-01-18
- 2.0.2 — 2022-01-15
- 2.0.1 — 2022-01-15
- 2.0.0 — 2022-01-15
- … 6 more at https://npm.io/package/element-props/versions

## README

# element-props <!--[![status](https://travis-ci.org/spectjs/element-props.svg)](https://travis-ci.org/spectjs/element-props)--> [![test](https://github.com/spectjs/element-props/actions/workflows/test.yml/badge.svg)](https://github.com/spectjs/element-props/actions/workflows/test.yml) [![size](https://img.shields.io/bundlephobia/minzip/element-props?label=size)](https://bundlephobia.com/result?p=element-props)

Normalize access to element attributes/properties.

[![npm i element-props](https://nodei.co/npm/element-props.png?mini=true)](https://nodei.co/npm/element-props/)

```js
import elementProps from 'element-props.js'

let el = document.getElementById('my-element')
props = elementProps(el, { z: Number })

// numeric
props.x = 1
el.getAttribute('x') // '1'
props.x // 1

// boolean
el.setAttribute('disabled', '')
props.disabled // true
props.disabled = false
el.getAttribute('disabled') // 'false'
props.disabled = null
el.getAttribute('disabled') // null

// functions
props.onclick = e => ()

// spread
{...props} // { y: false, x: 1, id: 'my-element' }
```

## API

### props = elementProps(element, types?, onchange?)

Create `props` for an `element`, with optional `types = { propName: Type }` (compat. with [attr-types](https://github.com/qwtel/attr-types)).<br/>
_Type_ is any data class like _Number_, _Boolean_, _String_, _Array_, _Object_, _Data_, _RegExp_, or `string => data` function like _JSON.parse_ (used for _Array_ and _Object_).

```js
import elementProps from 'element-props';

let props = elementProps(el, {n:Number, b:Boolean, o:Object, a:Array, s:String, d:Date}, (key, val) => {})
props.n = '1'
el.setAttribute('b', '')
el.s = 'abc'
el.setAttribute('a', '1,2,3')
el.setAttribute('o', '{foo:"bar"}')

{...props} // {n: 1, b: true, s: 'abc', o: {foo:'bar'}, a: [1,2,3]}
```

`props` handle input elements - _text_, _checkbox_, _select_:

```js
let el = document.querySelector('#checkbox')
let props = elementProps(el)
props.value = true

el.value // 'on'
el.checked // true
props.value // true
el.getAttribute('value') // 'on'
el.getAttribute('checked') // ''
```

### prop(el, key, value)

Set `key` prop/attribute value depending on value type.

* `on*` property can only be a function.
* `onEvt` === `onevt`.
* `style` can only be an object or a string.
* `class` can be a string, object or a string.
* `id` can only be a string.
* Empty strings are considered booleans: `<a disabled />` → `a.props.disabled === true`

CamelCase key name is mapped to dash-case for attribute.

### [get, set] = input(el)

Create getter/setter for an input depending on element type.

### value = parse(string, Type?)

Convert string value into defined type _or_ detect type automatically (tiny _auto-parse_).

```js
import { parse } from './element-props.js'

parse('true', Boolean) // true
parse('123') // 123
parse('1,2,3', Array) // [1, 2, 3]
parse('{ a: 1, b: 2 }', Object) // { a: 1, b: 2}
```


### polyfill

Add `props` to all HTML elements by including augment for `Element.prototype.props`:

```js
import 'element-props/augment.js'

document.body.id = 'my-body'
document.body.props // { id: 'my-body' }
```

### Design

Internally uses _Proxy_, (no IE11 support, but in theory possible with  _MutationObserver_ fallback)

Inspired by this [tweet](https://twitter.com/WebReflection/status/1260948278977409026?s=20) with spreading [hint](https://github.com/tc39/proposal-object-rest-spread/issues/69#issuecomment-633232470).

## See also

* [Element properties proposal](https://github.com/developit/unified-element-properties-proposal)
* [templize](https://github.com/spectjs/templize)
* [attr-types](https://github.com/qwtel/attr-types)

## License

ISC © Dmitry Iv.

<p align="center">ॐ</p>

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