{"id":13475293,"url":"https://github.com/choojs/nanocomponent","last_synced_at":"2025-03-26T23:30:40.437Z","repository":{"id":52948876,"uuid":"78044158","full_name":"choojs/nanocomponent","owner":"choojs","description":"🚃 - create performant HTML components","archived":false,"fork":false,"pushed_at":"2021-04-12T17:41:59.000Z","size":536,"stargazers_count":366,"open_issues_count":12,"forks_count":30,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-10-30T08:51:32.489Z","etag":null,"topics":["choo","component","dom","events"],"latest_commit_sha":null,"homepage":"https://leaflet.choo.io/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/choojs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2017-01-04T19:03:00.000Z","updated_at":"2024-08-30T10:54:13.000Z","dependencies_parsed_at":"2022-09-09T00:52:38.314Z","dependency_job_id":null,"html_url":"https://github.com/choojs/nanocomponent","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/choojs%2Fnanocomponent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/choojs%2Fnanocomponent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/choojs%2Fnanocomponent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/choojs%2Fnanocomponent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/choojs","download_url":"https://codeload.github.com/choojs/nanocomponent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245753827,"owners_count":20666819,"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":["choo","component","dom","events"],"created_at":"2024-07-31T16:01:19.149Z","updated_at":"2025-03-26T23:30:40.033Z","avatar_url":"https://github.com/choojs.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# nanocomponent [![stability][0]][1]\n\n[![npm version][2]][3] [![build status][4]][5]\n[![downloads][8]][9] [![js-standard-style][10]][11]\n\nNative DOM components that pair nicely with DOM diffing algorithms.\n\n## Features\n\n- Isolate native DOM libraries from DOM diffing algorithms\n- Makes rendering elements _very fast™_ by avoiding unnecessary rendering\n- Component nesting and state update passthrough\n- Implemented in only a few lines\n- Only uses native DOM methods\n- Class based components offering a familiar component structure\n- Works well with [nanohtml][nanohtml] and [yoyoify][yoyoify]\n- Combines the best of `nanocomponent@5` and [`cache-component@5`][cc].\n\n## Usage\n\n```js\n// button.js\nvar Nanocomponent = require('nanocomponent')\nvar html = require('nanohtml')\n\nclass Button extends Nanocomponent {\n  constructor () {\n    super()\n    this.color = null\n  }\n\n  createElement (color) {\n    this.color = color\n    return html`\n      \u003cbutton style=\"background-color: ${color}\"\u003e\n        Click Me\n      \u003c/button\u003e\n    `\n  }\n\n  // Implement conditional rendering\n  update (newColor) {\n    return newColor !== this.color\n  }\n}\n\nmodule.exports = Button\n```\n\n```js\n// index.js\nvar choo = require('choo')\nvar html = require('nanohtml')\n\nvar Button = require('./button.js')\nvar button = new Button()\n\nvar app = choo()\napp.route('/', mainView)\napp.mount('body')\n\nfunction mainView (state, emit) {\n  return html`\n    \u003cbody\u003e\n      ${button.render(state.color)}\n    \u003c/body\u003e\n  `\n}\n\napp.use(function (state, emitter) {\n  state.color = 'green'\n})\n```\n\n## Patterns\n\nThese are some common patterns you might encounter when writing components.\n\n### Standalone\n\nNanocomponent is part of the choo ecosystem, but works great standalone!\n\n```js\nvar Button = require('./button.js')\nvar button = new Button()\n\n// Attach to DOM\ndocument.body.appendChild(button.render('green'))\n\n// Update mounted component\nbutton.render('green')\nbutton.render('red')\n\n// Log a reference to the mounted dom node\nconsole.log(button.element)\n```\n\n### Binding event handlers as component methods\n\nSometimes it's useful to pass around prototype methods into other functions.\nThis can be done by binding the method that's going to be passed around:\n\n```js\nvar Nanocomponent = require('nanocomponent')\nvar html = require('nanohtml')\n\nclass Component extends Nanocomponent {\n  constructor () {\n    super()\n\n    // Bind the method so it can be passed around\n    this.handleClick = this.handleClick.bind(this)\n  }\n\n  handleClick (event) {\n    console.log('element is', this.element)\n  }\n\n  createElement () {\n    return html`\u003cbutton onclick=${this.handleClick}\u003e\n      My component\n    \u003c/button\u003e`\n  }\n\n  update () {\n    return false // Never re-render\n  }\n}\n```\n\n### ES5 Syntax\n\nNanocomponent can be written using prototypal inheritance too:\n\n```js\nvar Nanocomponent = require('nanocomponent')\nvar html = require('nanohtml')\n\nfunction Component () {\n  if (!(this instanceof Component)) return new Component()\n  Nanocomponent.call(this)\n  this.color = null\n}\n\nComponent.prototype = Object.create(Nanocomponent.prototype)\n\nComponent.prototype.createElement = function (color) {\n  this.color = color\n  return html`\n    \u003cdiv style=\"background-color: ${color}\"\u003e\n      Color is ${color}\n    \u003c/div\u003e\n  `\n}\n\nComponent.prototype.update = function (newColor) {\n  return newColor !== this.color\n}\n```\n\n### Mutating the components instead of re-rendering\n\nSometimes you might want to mutate the element that's currently mounted, rather\nthan performing DOM diffing. Think cases like third party widgets that manage\nthemselves.\n\n```js\nvar Nanocomponent = require('nanocomponent')\nvar html = require('nanohtml')\n\nclass Component extends Nanocomponent {\n  constructor () {\n    super()\n    this.text = ''\n  }\n\n  createElement (text) {\n    this.text = text\n    return html`\u003ch1\u003e${text}\u003c/h1\u003e`\n  }\n\n  update (text) {\n    if (text !== this.text) {\n      this.text = text\n      this.element.innerText = this.text   // Directly update the element\n    }\n    return false                           // Don't call createElement again\n  }\n\n  unload (text) {\n    console.log('No longer mounted on the DOM!')\n  }\n}\n```\n\nPlease note that if you remove a component from the DOM, it will be unloaded, and when reinserted into the DOM, `createElement` will be fired again. If you want to maintain control of a component's rendering, it has to stay mounted! See [issue #88](https://github.com/choojs/nanocomponent/issues/88) for a more detailed discussion.\n\n### Nested components and component containers\n\nComponents nest and can skip renders at intermediary levels.  Components can\nalso act as containers that shape app data flowing into view specific\ncomponents.\n\n```js\nvar Nanocomponent = require('nanocomponent')\nvar html = require('nanohtml')\nvar Button = require('./button.js')\n\nclass Component extends Nanocomponent {\n  constructor () {\n    super()\n    this.button1 = new Button()\n    this.button2 = new Button()\n    this.button3 = new Button()\n  }\n\n  createElement (state) {\n    var colorArray = shapeData(state)\n    return html`\n      \u003cdiv\u003e\n        ${this.button1.render(colorArray[0])}\n        ${this.button2.render(colorArray[1])}\n        ${this.button3.render(colorArray[2])}\n      \u003c/div\u003e\n    `\n  }\n\n  update (state) {\n    var colorArray = shapeData(state) // process app specific data in a container\n    this.button1.render(colorArray[0]) // pass processed data to owned children components\n    this.button2.render(colorArray[1])\n    this.button3.render(colorArray[2])\n    return false // always return false when mounted\n  }\n}\n\n// Some arbitrary data shaping function\nfunction shapeData (state) {\n  return [state.colors.color1, state.colors.color2, state.colors.color3]\n}\n```\n\n## FAQ\n\n### What order do lifecycle events run in?\n\n![Lifecycle diagram](lifecycle.jpg)\n\n**Note:** `aftercreate` should actually say `afterupdate`.\n\nShoutout to [@lrlna](https://github.com/lrlna) for the excellent diagram.\n\n### Where does this run?\n\nNanocomponent was written to work well with [choo][choo], but it also works well\nwith DOM diffing engines that check `.isSameNode()` like [nanomorph][nm] and\n[morphdom][md].  It is designed and documented in isolation however, so it also\nworks well on it's own if you are careful.  You can even embed it in other SPA\nframeworks like React or Preact with the use of [nanocomponent-adapters][nca] which\nenable framework-free components! 😎\n\n### What's a proxy node?\n\nIt's a node that overloads `Node.isSameNode()` to compare it to another node.\nThis is needed because a given DOM node can only exist in one DOM tree at the\ntime, so we need a way to reference mounted nodes in the tree without actually\nusing them. Hence the proxy pattern, and the recently added support for it in\ncertain diffing engines:\n\n```js\nvar html = require('nanohtml')\n\nvar el1 = html`\u003cdiv\u003epink is the best\u003c/div\u003e`\nvar el2 = html`\u003cdiv\u003eblue is the best\u003c/div\u003e`\n\n// let's proxy el1\nvar proxy = html`\u003cdiv\u003e\u003c/div\u003e`\nproxy.isSameNode = function (targetNode) {\n  return (targetNode === el1)\n}\n\nel1.isSameNode(el1)   // true\nel1.isSameNode(el2)   // false\nproxy.isSameNode(el1) // true\nproxy.isSameNode(el2) // false\n```\n\n### How does it work?\n\n[`nanomorph`][nm] is a diffing engine that diffs real DOM trees. It runs a series\nof checks between nodes to see if they should either be replaced, removed,\nupdated or reordered. This is done using a series of property checks on the\nnodes.\n\n[`nanomorph`][nm] runs `Node.isSameNode(otherNode)` when diffing two DOM trees. This\nallows us to override the function and replace it with a custom function that\nproxies an existing node. Check out the code to see how it works. The result is\nthat if every element in our tree uses `nanocomponent`, only elements that have\nchanged will be recomputed and re-rendered making things very fast.\n\n`nanomorph`, which saw first use in choo 5, has supported `isSameNode` since\nits conception. [`morphdom`][md] has supported `.isSameNode` since [v2.1.0][210].\n\n### Is this basically `react-create-class`?\n\n`nanocomponent` is very similar to `react-create-class`, but it leaves more decisions up\nto you.  For example, there is no built in `props` or `state` abstraction in `nanocomponent`\nbut you can do something similar with `arguments` (perhaps passing a single `props` object\nto `.render` e.g. `.render({ foo, bar })` and assigning internal state to `this` however\nyou want (perhaps `this.state = { fizz: buzz }`).\n\n## API\n\n### `component = Nanocomponent([name])`\n\nCreate a new Nanocomponent instance. Additional methods can be set on the\nprototype. Takes an optional name which is used when emitting timings.\n\n### `component.render([arguments…])`\n\nRender the component. Returns a proxy node if already mounted on the DOM. Proxy\nnodes make it so DOM diffing algorithms leave the element alone when diffing.  Call this when `arguments` have changed.\n\n### `component.rerender()`\n\nRe-run `.render` using the last `arguments` that were passed to the `render` call.  Useful for triggering component renders if internal state has changed.  Arguments are automatically cached under `this._arguments` (🖐 hands off, buster! 🖐).  The `update` method is bypassed on re-render.\n\n### `component.element`\n\nA [getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get)\nproperty that returns the component's DOM node if its mounted in the page and\n`null` when its not.\n\n### `DOMNode = Nanocomponent.prototype.createElement([arguments…])`\n\n__Must be implemented.__ Component specific render function.  Optionally cache\nargument values here.  Run anything here that needs to run along side node\nrendering.  Must return a DOMNode. Use `beforerender` to run code after\n`createElement` when the component is unmounted.  Previously named `_render`.  Arguments passed to `render` are passed to `createElement`.  Elements returned from `createElement` must always return the same root node type.\n\n### `Boolean = Nanocomponent.prototype.update([arguments…])`\n\n__Must be implemented.__ Return a boolean to determine if\n`prototype.createElement()` should be called.  The `update` method is analogous to\nReact's `shouldComponentUpdate`. Called only when the component is mounted in\nthe DOM tree.  Arguments passed to `render` are passed to `update`.\n\n### `Nanocomponent.prototype.beforerender(el)`\n\nA function called right after `createElement` returns with `el`, but before the fully rendered\nelement is returned to the `render` caller. Run any first render hooks here. The `load` and\n`unload` hooks are added at this stage.  Do not attempt to `rerender` in `beforerender` as the component may not be in the DOM yet.\n\n### `Nanocomponent.prototype.load(el)`\n\nCalled when the component is mounted on the DOM. Uses [on-load][onload] under\nthe hood.\n\n### `Nanocomponent.prototype.unload(el)`\n\nCalled when the component is removed from the DOM. Uses [on-load][onload] under\nthe hood.\n\n### `Nanocomponent.prototype.afterupdate(el)`\n\nCalled after a mounted component updates (e.g. `update` returns true).  You can use this hook to call\n`element.scrollIntoView` or other dom methods on the mounted component.\n\n### `Nanocomponent.prototype.afterreorder(el)`\n\nCalled after a component is re-ordered.  This method is rarely needed, but is handy when you have a component\nthat is sensitive to temorary removals from the DOM, such as externally controlled iframes or embeds (e.g. embedded tweets).\n\n## Installation\n\n```sh\n$ npm install nanocomponent\n```\n\n## Optional lifecycle events\n\nYou can add even more lifecycle events to your components by attatching the following modules\nin the `beforerender` hook.\n\n- [yoshuawuyts/observe-resize](https://github.com/yoshuawuyts/observe-resize)\n- [bendrucker/document-ready](https://github.com/bendrucker/document-ready)\n- [yoshuawuyts/on-intersect](https://github.com/yoshuawuyts/on-intersect)\n- [yoshuawuyts/on-idle](https://github.com/yoshuawuyts/on-idle)\n\n## See also\n\n- [component-box][cb] - Dynamic component instance caching\n- [nanomap][nanomap] - Functional mapping into keyed component instances\n- [choojs/choo][choo]\n- [choojs/nanocomponent-adapters][nca]\n- [choojs/nanohtml](https://github.com/choojs/nanohtml)\n- [shama/on-load](https://github.com/shama/on-load)\n\n## Examples\n\n- [Bloomberg: What’s Inside All the iPhones](https://www.bloomberg.com/features/apple-iphone-guts/) (👏 [@jongacnik](https://github.com/jongacnik) 👏)\n- [twitter-component](https://github.com/bcomnes/twitter-component)\n- [youtube-component](https://github.com/bcomnes/youtube-component)\n- [Ara File Manager](https://ara.one/app) (Decentralized application built atop Electron)\n\n## Similar Packages\n\n- [shama/base-element](https://github.com/shama/base-element)\n- [yoshuawuyts/cache-element](https://github.com/yoshuawuyts/cache-element)\n- [yoshuawuyts/microcomponent](https://github.com/yoshuawuyts/microcomponent)\n- [hypermodules/cache-component](https://github.com/hypermodules/cache-component)\n- [rafaelrinaldi/data-components](https://github.com/rafaelrinaldi/data-components)\n\n## License\n\n[MIT](https://tldrlegal.com/license/mit-license)\n\n[0]: https://img.shields.io/badge/stability-experimental-orange.svg?style=flat-square\n[1]: https://nodejs.org/api/documentation.html#documentation_stability_index\n[2]: https://img.shields.io/npm/v/nanocomponent.svg?style=flat-square\n[3]: https://npmjs.org/package/nanocomponent\n[4]: https://img.shields.io/travis/choojs/nanocomponent/master.svg?style=flat-square\n[5]: https://travis-ci.org/choojs/nanocomponent\n[8]: http://img.shields.io/npm/dm/nanocomponent.svg?style=flat-square\n[9]: https://npmjs.org/package/nanocomponent\n[10]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square\n[11]: https://github.com/feross/standard\n[nanohtml]: https://github.com/choojs/nanohtml\n[yoyoify]: https://github.com/shama/yo-yoify\n[md]: https://github.com/patrick-steele-idem/morphdom\n[210]: https://github.com/patrick-steele-idem/morphdom/pull/81\n[nm]: https://github.com/yoshuawuyts/nanomorph\n[ce]: https://github.com/yoshuawuyts/cache-element\n[class]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes\n[isSameNode]: https://github.com/choojs/nanomorph#caching-dom-elements\n[onload]: https://github.com/shama/on-load\n[choo]: https://github.com/choojs/choo\n[nca]: https://github.com/choojs/nanocomponent-adapters\n[cc]: https://github.com/hypermodules/cache-component\n[nanomap]: https://github.com/bcomnes/nanomap\n[cb]: https://github.com/jongacnik/component-box\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchoojs%2Fnanocomponent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchoojs%2Fnanocomponent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchoojs%2Fnanocomponent/lists"}