{"id":25522277,"url":"https://github.com/launchscout/live_elements","last_synced_at":"2025-04-12T21:29:32.511Z","repository":{"id":125227052,"uuid":"609672764","full_name":"launchscout/live_elements","owner":"launchscout","description":"A library to make custom elements and LiveView so happy together","archived":false,"fork":false,"pushed_at":"2025-02-16T18:06:10.000Z","size":98,"stargazers_count":122,"open_issues_count":2,"forks_count":6,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-04T01:15:43.941Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","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/launchscout.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-04T22:06:44.000Z","updated_at":"2025-03-23T01:18:34.000Z","dependencies_parsed_at":"2023-12-16T23:49:11.932Z","dependency_job_id":"18084388-d128-43bd-9967-9eaf47d26521","html_url":"https://github.com/launchscout/live_elements","commit_stats":{"total_commits":10,"total_committers":1,"mean_commits":10.0,"dds":0.0,"last_synced_commit":"2b8fe4a33d0d58ef20bfc7f14e4f52af76640c97"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchscout%2Flive_elements","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchscout%2Flive_elements/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchscout%2Flive_elements/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchscout%2Flive_elements/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/launchscout","download_url":"https://codeload.github.com/launchscout/live_elements/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248634451,"owners_count":21137047,"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":"2025-02-19T18:19:12.237Z","updated_at":"2025-04-12T21:29:32.492Z","avatar_url":"https://github.com/launchscout.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LiveElements\n\n## Goals\nThe goal of LiveElements is to improve the ergonomics of integrating custom HTML elements with [Phoenix LiveView](https://hexdocs.pm/phoenix_live_view). \n\n## Non-goals\nThis project assumes\nyou are using custom elements on a page served by phoenix. If you are building custom elements \nthat need to talk to a phoenix app but live on a page not served by phoenix (on a statically generated site for example), you may want to check out [LiveState](https://hexdocs.pm/live_state) instead.\n\n## Description\n\nWe accomplish our goal by creating helper functions to make \nworking with custom elements just as easy as any other LiveView functional component.\n\nFor example, let's say you have a `\u003ctodo-list\u003e` custom element that has an attribute \nthat takes a list of todos, and emits an `add_todo` Custom Event. LiveElements will \ngenerate a helper function (details below) which will wrap the custom element like\nso:\n\n```heex\n\u003c.todo_list todos={@todos}\u003e\u003c/.todo_list\u003e\n```\n\nSerialization of todos to json happens automatically. In your live view you handle the `add_todo` event just like any other live view event:\n\n```elixir\n  def handle_event(\"add_todo\", %{\"todo\" =\u003e todo}, %{assigns: %{todos: todos}} = socket) do\n    {:noreply, socket |\u003e assign(todos: todos ++ [todo])}\n  end\n```\n\n## Installation\n\n### Install hex package\n\nIf [available in Hex](https://hex.pm/docs/publish), the package can be installed\nby adding `live_elements` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:live_elements, \"~\u003e 0.2.1\"}\n  ]\nend\n```\n\n### Install Custom Events hook\n\nPresuming your custom element emits custom events you want to handle in live view, you'll need to install the `phoenix-custom-event-hook` npm package and add the hook \nto the live socket.\n\nTo install (from project dir):\n\n```\nnpm install --prefix assets phoenix-custom-event-hook\n```\n\nThen, in `app.js` (or wherever you set up your live socket):\n\n```js\nimport PhoenixCustomEventHook from 'phoenix-custom-event-hook';\n\nlet csrfToken = document.querySelector(\"meta[name='csrf-token']\").getAttribute(\"content\")\nlet liveSocket = new LiveSocket(\"/live\", Socket, {params: {_csrf_token: csrfToken}, hooks: {PhoenixCustomEventHook}})\n```\n\n# Usage\n\nIn the LiveViews where you want to call custom element helper functions do:\n\n```\nuse LiveElements.CustomElementsHelpers\n```\n\nThis will add helper functions for any custom elements found in your manifest file, if\nyou have one configured, as well as importing the `custom_element` macro.\n\n## Producing helper functions from a custom elements manifest file\n\nLiveElements can consume a [custom elements manifest file](https://github.com/webcomponents/custom-elements-manifest) to produce helper functions\nat compile time. To do so, in your config:\n\n```elixir\nconfig :live_elements, \n  custom_elements_manifest: Path.expand(\"../assets/custom-elements.json\", __DIR__)\n```\n\nTo produce a manifest file automatically from your custom element source code, you might want to check out the [custom element analyzer](https://custom-elements-manifest.open-wc.org/analyzer/getting-started/) from open-wc.org.\n\n## Using the `custom_element` macro\n\nIf you are using a library that does not have a manifest, or don't wish to use one, you can \nalso use the `custom_element` macro like so:\n\n```elixir\n  custom_element :bx_data_table, events: [\"bx-table-header-cell-sort\"]\n```\n\nThis would then allow you to call `\u003c.bx_data_table\u003e` in your live view and `handle_event(\"bx-table-header-cell-sort\", ...)` to respond to events.\n\n# Example\n\nThe [live_elements_testbed](https://github.com/launchscout/live_elements_testbed) contains an \nexample phoenix liveview app demonstrating all of the features of live_elements, as well as\nintegration tests for the live_elements project.\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchscout%2Flive_elements","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaunchscout%2Flive_elements","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchscout%2Flive_elements/lists"}