{"id":22283672,"url":"https://github.com/fennifith/declarativ","last_synced_at":"2025-07-28T21:32:55.428Z","repository":{"id":55820508,"uuid":"206341177","full_name":"fennifith/declarativ","owner":"fennifith","description":"A declarative HTML rendering library that is definitely not JSX.","archived":false,"fork":false,"pushed_at":"2020-12-11T19:53:49.000Z","size":450,"stargazers_count":20,"open_issues_count":9,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-29T16:41:54.590Z","etag":null,"topics":["declarative-ui","html","javascript","jquery","nodejs","npm","promises"],"latest_commit_sha":null,"homepage":"https://declarativ.js.org/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fennifith.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":"2019-09-04T14:39:20.000Z","updated_at":"2022-03-14T23:46:43.000Z","dependencies_parsed_at":"2022-08-15T07:21:19.556Z","dependency_job_id":null,"html_url":"https://github.com/fennifith/declarativ","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fennifith%2Fdeclarativ","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fennifith%2Fdeclarativ/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fennifith%2Fdeclarativ/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fennifith%2Fdeclarativ/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fennifith","download_url":"https://codeload.github.com/fennifith/declarativ/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227960182,"owners_count":17847752,"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":["declarative-ui","html","javascript","jquery","nodejs","npm","promises"],"created_at":"2024-12-03T16:41:35.012Z","updated_at":"2024-12-03T16:41:35.808Z","avatar_url":"https://github.com/fennifith.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Declarativ\n[![Build Status](https://github.com/fennifith/declarativ/workflows/NodeJS%20Package/badge.svg)](https://github.com/fennifith/declarativ/actions)\n[![NPM Package](https://img.shields.io/npm/v/declarativ?color=red\u0026logo=npm)](https://www.npmjs.com/package/declarativ)\n[![Discord](https://img.shields.io/discord/514625116706177035.svg?logo=discord\u0026colorB=7289da)](https://discord.jfenn.me/)\n[![Liberapay](https://img.shields.io/badge/liberapay-donate-yellow.svg?logo=liberapay)](https://jfenn.me/links/liberapay)\n=======\n\n\"Declarativ\" is a lightweight and asynchronous HTML templating library for JavaScript. It definitely isn't my own reinvention of React's [JSX](https://reactjs.org/docs/introducing-jsx.html). Okay, it kind of is, but whatever, it's still cool.\n\nDeclarativ allows you to write a document tree using a series of nested function calls, much like how Declarative UI works inside [Flutter](https://flutter.dev/docs/get-started/flutter-for/declarative#how-to-change-ui-in-a-declarative-framework) or in [Jetpack Compose](https://developer.android.com/jetpack/compose). Here's an example:\n\n```js\ncontainer(\n  jumbotron(\n    h1(\"This is a big header.\"),\n    button(\"Do something\").on(\"click\", () =\u003e alert(\"Hello!\")),\n    p($.get(\"https://loripsum.net/api/plaintext\"))\n  )\n)\n```\n\n## Installation\n\n#### Script Tag\n\n```html\n\u003cscript type=\"text/javascript\" src=\"https://unpkg.com/declarativ@0.1.7/dist/declarativ.min.js\"\u003e\u003c/script\u003e\n```\n\n(the module will be included in the global scope as the `declarativ` variable)\n\n#### NPM/Webpack\n\n```sh\nnpm install declarativ\n```\n\n#### From Source\n\n```sh\ngit clone https://github.com/fennifith/declarativ.git\ncd declarativ \u0026\u0026 make install\n```\n\n## Usage\n\nMost component trees can be built using the standard functions defined in `declarativ.el`. I often use [destructuring assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) to move them to the current scope when using more than one or two of them, which makes it a bit easier to work with (provided you don't use any variables that conflict with the element names). Here's an example:\n\n```js\nconst { div, h1, p, a } = declarativ.el;\n\nlet components = div(\n  h1(\"This is a big header.\"),\n  p(\n    \"Here, have a bit of text\",\n    a(\"and a link\").attr(\"href\", \"https://example.com/\"),\n    \".\"\n  )\n);\n```\n\nAfter defining your component tree, it can be placed on the DOM by either calling the `render` or `renderString` functions. Calling `render` will place them inside whatever element (or selector) you pass as its argument, while `renderString` simply returns their HTML representation.\n\n```js\ncomponents.render(\"#content\").then(() =\u003e {\n    console.log(\"Elements rendered!\");\n});\n```\n\nWorking examples can be found in the [examples](../../tree/master/docs/examples/) folder.\n\n### Promises \u0026 Asynchronicity\n\nPromises can be mixed in with components, and declarativ will wait for them to resolve before processing the result.\n\n```js\np(\n  \"Everything in this example \",\n  new Promise((resolve) =\u003e {\n    setTimeout(() =\u003e resolve(\"will all render \"), 1000);\n  }),\n  new Promise((resolve) =\u003e {\n    setTimeout(() =\u003e resolve(\"at the exact same \"), 2000);\n  }),\n  \"time!\"\n)\n```\n\nThis happens a bit differently when using the `.bind` method; components that are unbound will render first, and any children within a bound component will wait for its promise to resolve before being processed.\n\n```js\ndiv(\n  p(\"This will render first.\"),\n  p(\"This will render second.\").bind(new Promise((resolve) =\u003e {\n    setTimeout(() =\u003e resolve(), 1000);\n  })),\n  p(\"This will render last.\").bind(new Promise((resolve) =\u003e {\n    setTimeout(() =\u003e resolve(\"at the exact same\"), 2000);\n  }))\n)\n```\n\n### Handling Data\n\nNodes can exist in various forms inside of a component. In the last example, I specified a Promise and a string as the contents of a paragraph element. However, not all of the promises you use will return a string. Often times, you will handle data structures that need to be bound to multiple elements. This is where the `.bind()` function comes in useful.\n\n```js\ndiv(\n  p(\"This will render first\"),\n  div(\n    p((data) =\u003e data.first),\n    p((data) =\u003e data.second)\n  ).bind(Promise.resolve({\n    first: \"This is a string.\",\n    second: \"This is another string.\"\n  }))\n)\n```\n\nOkay, a lot is happening here. I'll slow down and explain.\n\nThe `bind` function _also_ allows you to specify a set of data to be passed to other parts of a component - and extends upon the types of nodes that can be placed inside it. Because the paragraph elements inside the div are not bound to any data, they inherit the Promise that is bound to their parent. The nodes inside of the paragraph elements are then specified as a function of the resolved data, returning the text to render.\n\nA more complex data binding situation based off the GitHub API can be found in [examples/binding.html](./docs/examples/binding.html).\n\n### Templates\n\nTemplating functionality is crucial for projects that involve a large number of elements or repeat a common set of element structures in multiple places. There are a few different ways to create them:\n\n#### Functions\n\nThe easiest is to just create a function that returns another component, like so:\n\n```js\nfunction myComponent(title, description) {\n  return div(\n    h3(title),\n    p(description)\n  );\n}\n```\n\nBecause you're just passing the arguments directly into the structure, this allows you to pass your function a string, another component, a function(data), or a Promise, and have it resolve during the render.\n\n#### Wrapped Components\n\nIf you want to make a component that just slightly extends upon an existing instance of one, it can be wrapped in a function that will act like other components during use. This isn't useful very often, as any child components will be lost in the process, but it is useful if you just want to add a class name or attribute to a component without defining a structure.\n\n```js\nconst myComponent = declarativ.wrapCompose(\n  div().className(\"fancypants\")\n);\n``` \n\n#### Custom Elements\n\nThis is possibly the least useful kind of template, but I'll leave it here anyway. Most elements are specified inside `declarativ.elements`, but in the event that you want to use one that isn't, you can create an element template by calling `declarativ.compose()` with a template function.\n\nBy \"template function\", it must be a function that accepts a string and returns that string inside of the element's HTML tag. For example, here I implement the deprecated `\u003ccenter\u003e` tag.\n\n```js\nconst myComponent = declarativ.compose((inner) =\u003e `\u003ccenter\u003e${inner}\u003c/center\u003e`);\n```\n\nWorking examples of all of these templates can be found in [examples/templates.html](./docs/examples/templates.html). \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffennifith%2Fdeclarativ","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffennifith%2Fdeclarativ","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffennifith%2Fdeclarativ/lists"}