{"id":20513745,"url":"https://github.com/webreflection/reactive-props","last_synced_at":"2025-04-14T00:01:58.915Z","repository":{"id":57348206,"uuid":"297066273","full_name":"WebReflection/reactive-props","owner":"WebReflection","description":"An all-in-one implementation of the Reactive State for Data \u0026 DOM patterns.","archived":false,"fork":false,"pushed_at":"2021-01-30T09:21:44.000Z","size":62,"stargazers_count":31,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-27T14:11:09.943Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://medium.com/@WebReflection/reactive-state-for-data-dom-78332ddafd0e","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebReflection.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-20T11:58:46.000Z","updated_at":"2022-06-09T14:18:58.000Z","dependencies_parsed_at":"2022-08-31T17:51:05.783Z","dependency_job_id":null,"html_url":"https://github.com/WebReflection/reactive-props","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Freactive-props","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Freactive-props/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Freactive-props/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Freactive-props/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebReflection","download_url":"https://codeload.github.com/WebReflection/reactive-props/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248799931,"owners_count":21163403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T21:12:53.357Z","updated_at":"2025-04-14T00:01:58.890Z","avatar_url":"https://github.com/WebReflection.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# reactive-props\n\n[![Build Status](https://travis-ci.com/WebReflection/reactive-props.svg?branch=master)](https://travis-ci.com/WebReflection/reactive-props) [![Coverage Status](https://coveralls.io/repos/github/WebReflection/reactive-props/badge.svg?branch=master)](https://coveralls.io/github/WebReflection/reactive-props?branch=master)\n\nAn all-in-one implementation of the [Reactive State for Data \u0026 DOM](https://medium.com/@WebReflection/reactive-state-for-data-dom-78332ddafd0e) patterns, compatible down to IE9.\n\n\n### Live Examples\n\n  * **[test page](https://webreflection.github.io/reactive-props/test/)** to be sure your target browser is compatible (IE9+)\n  * **[wickedElements](https://github.com/WebReflection/wicked-elements#readme)** usage [live demo](https://codepen.io/WebReflection/pen/RwaYzjE)\n  * **[µce](https://github.com/WebReflection/uce#readme)** usage [live demo](https://codepen.io/WebReflection/pen/LYNJwoV)\n  * **[µland](https://github.com/WebReflection/uland#readme)** usage [live demo](https://codepen.io/WebReflection/pen/YzqOoRB)\n  * **[hookedElements](https://github.com/WebReflection/hooked-elements#readme)** usage [live demo](https://codepen.io/WebReflection/pen/qBZMJeX)\n\n\n## API\n\nThis module exports a default helper function that can create utilities to define reactive properties / states for data or DOM elements.\nFor documentation sake, this function will be named `createHandler`, and it accepts an optional configuration object, with the following properties:\n\n  * `all:boolean`, signals that all set properties should invoke the related update. If `true`, even if a property has the same value it had before, the related update function will be invoked.\n  * `shallow:boolean`, signals that that even if the property value is the same, the update should happen in case it's the same object, or the same array, set before. If `false`, and `all = false` too (default), no update happens in case the object is the exact same as before.\n  * `dom:boolean`, signals that properties will be attached to a DOM element, which needs to be passed along. By default, the returned utility to create reactive properties has a `(props[, update])` signature, but when `dom = true`, the returned helper will have a `(element, props[, update])` signature. By default, `dom` is `false.\n  * `getAttribute(element, key):any` is an optional helper to retrieve the right value when `dom = true` and the element already had an attribute with the reactive property name. `\u003celement checked=\"true\"\u003e` will pass to this helper the `element` reference and the `checked` attribute name. By default, this helper returns `element.getAttribute(\"checked\")`, but it is possible to return `JSON.parse(element.getAttribute(\"checked\"))` instead, so that the initial `element.checked` will return a proper boolean value.\n  * `useState(value):void` is an optional helper that accepts any generic `useState` handler from any *hooks* based library. If provided, it will be invoked passing along the new value when all conditions are match (see previous `all` and `shallow` description)\n\nThe resulting helper returns either the `state` object with reactive properties, or the passed `element`.\n\n```js\n// for reactive states\nconst reactiveProps = createHandler();\nconst state = reactiveProps({...}, update);\n\n// for reactive elements\nconst reactiveElement = createHandler({dom: true});\nconst el = reactiveElement(document.querySelector('el'), {...}, update);\n```\n\nIf an `update` function is provided, it will be used to invoke state changes per each update, bypassing the possible `useState`.\n\n\n```js\nimport {useState} from 'augmentor';\n\nconst reactiveProps = createHandler({useState});\nconst state = reactiveProps({test: ''});\nstate.test = 'OK';\n// will invoke useState('OK')\n\nconst overload = reactiveProps({test: ''}, console.log);\noverload.test = 'OK';\n// will simply log \"OK\" without invoking useState(\"OK\")\n```\n\n\n#### Default Use Cases\n\nThe default value goal of all options is to cover these common use cases:\n\n  * *primitive properties* that would trigger updates only if different\n  * *non immutable data* that would trigger updates if properties are objects/arrays. Use `shallow = false` option if data is granted to be immutable deep down each inner value\n  * *integrated hooks* to work within a variety of libraries that offer a `useState` hook\n\nFor any other combined use case, please refer to [the related post](https://medium.com/@WebReflection/reactive-state-for-data-dom-78332ddafd0e) and find out your fine tuned reactive state handler.\n\n\n#### Partial Imports\n\nIf all you need is either the *state handler* or the *dom handler*, it is possible to import just those two separately, resulting in a slightly smaller bundle.\n\n```js\n// const genericHandler = require('reactive-props');\nimport genericHandler from 'reactive-props';\n\n// const domHandler = require('reactive-props/dom');\nimport domHandler from 'reactive-props/dom';\n\n// produces same results\ndomHandler();\ngenericHandler({dom: true});\n\n// const stateHandler = require('reactive-props/state');\nimport stateHandler from 'reactive-props/state';\n\n// produces same results\nstateHandler();\ngenericHandler({dom: false});\n```\n\n\n### Basic Example\n\n```js\n// const createHandler = require('reactive-props');\nimport createHandler from 'reactive-props';\n\nconst reactiveProps = createHandler();\nconst reactiveElement = createHandler({dom: true});\n\n// create reactive props\nconst state = reactiveProps(\n  // props to react for\n  {test: ''},\n  // called on each prop update\n  () =\u003e console.log(state)\n);\n\nstate.test;           // \"\"\nstate.test = 'value'; // {\"test\":\"value\"}\n\n// create reactive elements\nconst body = reactiveElement(\n  document.body,\n  {test: ''},\n  () =\u003e console.log('body.test', body.test)\n);\n\nbody.test;           // \"\"\nbody.test = 'value'; // body.test \"value\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebreflection%2Freactive-props","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebreflection%2Freactive-props","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebreflection%2Freactive-props/lists"}