phoenix_live_view changelog

Here's a roundup of the latest and greatest updates to the Phoenix LiveView framework, where we've been busy sprinkling in some magic to make your development experience even more delightful. Let's dive into the details! 🌟

  • New feature: Allow any selector as portal target 🎯
    We've leveled up the portal feature by allowing any CSS selector as a target for teleportation! Now you can send elements directly into the <body> or any other specified selector. This gives you superpowers in managing your DOM elements. Our team added a bunch of tests to make sure everything works like a charm. 🚀

  • New feature: Add event payload to phx:push events 📦
    Say hello to more flexible event handling! We've added an event payload feature to phx:push events, letting you capture and include the original event details. This means more control and customization for your LiveView interactions. 🎉

  • New feature: Introduce :key-ed :for comprehensions 🔑
    Optimize your change-tracking with our new :key-ed :for comprehensions. This feature transforms comprehension content into LiveComponents, making data payloads leaner and more efficient. Just remember, it's limited to HTML tags for now. 🏗️

  • Improvement: Allow inline matcher to be strings too 🔄
    We've made it easier to specify inline components by allowing the :inline_matcher option to accept strings! This makes configuring your inline elements more intuitive while still supporting regular expressions. 💡

  • New feature: Add option to treat custom components as inline 📝
    Customize your component formatting with the new :inline_matcher option. Now you can specify which components should be treated as inline elements, giving you more control over your HTML formatting. ✨

  • New feature: Update documentation with :reply example in handle_event 📚
    We've enriched our documentation with a shiny new example of using the :reply feature in the handle_event callback. Check it out to see how you can implement interactive features with ease. 📖

  • Bugfix: Ensure directory exists when writing empty manifest 🛠️
    We squashed a bug in the write_new_manifests! function by making sure the target directory exists before writing an empty manifest file. Smooth sailing from here on out! ⛵

  • Bugfix: Fix backticks and macro component example ✏️
    Our eagle-eyed team spotted and fixed some formatting issues with backticks and an example in the documentation. Now everything looks neat and tidy, just the way we like it. 🧹

These updates are all about making your life easier and your code cleaner. Enjoy the new features and improvements, and keep on building awesome things with Phoenix LiveView! 🎈

Included Commits

2025-06-13T10:00:10 See commit

This commit enhances the functionality of the portal feature in the Phoenix LiveView framework by allowing any CSS selector to be used as a target for teleportation, rather than restricting it to specific IDs. This change enables developers to teleport elements directly into the <body> tag or any other specified selector, providing greater flexibility in managing DOM elements. The implementation involved modifying the teleport method to use document.querySelector instead of document.getElementById, and adjusting error messages to reflect the new selector-based approach.

Additionally, the commit includes updates to various test files to ensure that the new functionality is thoroughly validated. This includes adding tests for teleportation behavior, event routing to the correct LiveView, and ensuring that streams work correctly within teleported LiveComponents. Overall, the changes aim to improve the usability and versatility of the portal feature, making it easier for developers to manage dynamic content in their applications.

Files changed

  • assets/js/phoenix_live_view/dom_patch.js
  • assets/test/integration/portal_test.ts
  • lib/phoenix_component.ex
  • test/e2e/support/portal.ex
  • test/e2e/tests/portal.spec.js
2025-06-13T17:40:35 See commit

This commit enhances the phx:push events in the Phoenix LiveView framework by adding an event payload feature. The changes involve modifications to the JavaScript files responsible for handling events, specifically js.js and view.js. The commit introduces a new property, originalEvent, to the pushOpts object, which captures the original event that triggered the phx:push. Additionally, the refGenerator function is updated to optionally accept a payload, which is then included in the event details dispatched through the phx:push event.

Furthermore, the commit also updates the handling of event options across various functions, ensuring that the new payload feature is integrated seamlessly into existing functionalities like form submissions and event pushes. The test file js_test.ts is also modified to validate the new behavior, confirming that the payload is correctly included in the event options. Overall, these changes improve the flexibility and functionality of event handling within the Phoenix LiveView framework.

Files changed

  • assets/js/phoenix_live_view/js.js
  • assets/js/phoenix_live_view/view.js
  • assets/test/js_test.ts
2025-06-14T17:03:39 See commit

The commit enhances the changelog by adding a new section dedicated to the portal feature introduced in LiveView 1.1. This feature allows developers to render parts of a component's template outside of its regular DOM hierarchy, which is particularly useful for UI elements like tooltips or dialogs that may be affected by CSS properties such as overflow: hidden. The commit details how the new Phoenix.Component.portal/1 component functions, enabling elements to be teleported into the body of the document while still maintaining event handling for phx-* events.

Additionally, the commit mentions the introduction of colocated hooks, allowing developers to define JavaScript hooks directly alongside their LiveView components. This update aims to improve usability and organization by ensuring that hooks are included in the regular JavaScript bundle. The changelog also provides examples and notes on how to adjust configurations for these new features, drawing parallels to similar functionalities in Vue.js and React. Co-authored by Ievgen Pyrogov, the commit reflects significant updates aimed at enhancing the developer experience with LiveView.

Files changed

  • CHANGELOG.md
2025-06-14T17:25:17 See commit

This commit addresses an issue in the write_new_manifests! function within the Phoenix.LiveView.ColocatedJS module by ensuring that the target directory exists before attempting to write an empty manifest file. Specifically, it adds a call to File.mkdir_p! to create the directory if it does not already exist, thereby preventing potential errors when trying to write the manifest.

The modification involves adding two lines of code that check if the files list is empty and, if so, create the necessary directory with File.mkdir_p!(target_dir()) before writing the index.js file. This change enhances the robustness of the code by ensuring that the directory structure is in place, thus allowing the writing process to proceed smoothly.

Files changed

  • lib/phoenix_live_view/colocated_js.ex
2025-06-15T13:17:27 See commit

This commit introduces :key-ed :for comprehensions to enhance the change-tracking capabilities in LiveComponents. By transforming the comprehension's content into a LiveComponent, this feature optimizes data payloads transmitted over the network. The new syntax requires developers to define the left-hand side of the :for comprehension using assign-syntax, which ensures that each item can be uniquely identified through a specified key. However, it's important to note that keyed comprehensions are limited to HTML tags and cannot be applied to function components or slots, which would result in a compile-time exception.

In addition to the new feature, the commit includes various updates such as documentation enhancements, the addition of tests for the keyed comprehension handling, and several code simplifications. The changes are reflected across multiple files, including updates to the LiveView engine and related test modules. Co-authored by José Valim, this commit aims to streamline the development experience while maintaining efficient data handling in LiveView applications.

Files changed

  • guides/server/assigns-eex.md
  • lib/phoenix_component.ex
  • lib/phoenix_live_view/engine.ex
  • lib/phoenix_live_view/keyed_comprehension.ex
  • lib/phoenix_live_view/tag_engine.ex
  • test/phoenix_live_view/diff_test.exs
  • test/phoenix_live_view/tag_engine_test.exs
2025-06-16T11:58:46 See commit

This commit enhances the documentation in the guides/client/js-interop.md file by adding an example of using the :reply feature within the handle_event callback in a Phoenix LiveView context. The new example demonstrates how to set up a client-side hook that listens for a click event, pushes an event to the LiveView, and handles the reply by logging a message to the console. The provided code snippets illustrate both the JavaScript hook implementation and the corresponding Elixir server-side event handling.

In addition to the new example, the commit retains existing content about implementing features like infinite scrolling, which can utilize data attributes for passing the current page. Overall, this update aims to clarify the usage of the :reply mechanism, making it easier for developers to understand and implement interactive features in their LiveView applications. The changes include 31 additions and 1 deletion, resulting in a total of 32 modifications to the documentation.

Files changed

  • guides/client/js-interop.md
2025-06-16T21:00:11 See commit

This commit updates the CHANGELOG.md to include a new section on keyed comprehensions in LiveView, detailing improvements made in version 1.1. It addresses a common issue where changes to collections rendered in LiveView lead to all elements being re-sent over the wire, even if only a single item is updated. The commit explains two previous solutions—using streams and LiveComponents—but highlights their limitations in terms of memory usage and the need for separate modules.

The new :key attribute for :for comprehensions allows developers to optimize their rendering by enabling granular diffs without the overhead of creating additional components. By using :key, LiveView can treat each item as a distinct LiveComponent while keeping the template inline, thus improving efficiency. The changelog notes that this optimization is currently limited to regular HTML tags but hints at potential future enhancements for components and slots.

Files changed

  • CHANGELOG.md
2025-06-17T09:25:21 See commit

This commit introduces a new feature in the Phoenix LiveView HTML formatter that allows developers to specify custom components as inline elements. The addition of the :inline_matcher option enables users to define a list of regular expressions that determine whether a component should be treated as inline. By default, the formatter recognizes components with "link" or "button" in their names as inline, but this behavior can be customized or disabled by providing an empty list.

The implementation includes modifications to the HTMLFormatter module, where the logic for handling inline elements is integrated into the existing formatting process. The commit also includes tests to ensure that components with specific names are correctly identified as inline or block elements, thereby maintaining the desired formatting behavior. Overall, this enhancement provides greater flexibility for developers in formatting their custom components within Phoenix LiveView applications.

Files changed

  • lib/phoenix_live_view/html_formatter.ex
  • test/phoenix_live_view/html_formatter_test.exs
2025-06-17T11:25:11 See commit

This commit addresses an issue with the example provided in the comments of the macro_component.ex file within the Phoenix framework. The changes involve modifying the return value in the example to correctly reflect the expected output format, changing it from {"div", attrs, [html_doc]} to {:ok, {"div", attrs, [html_doc]}}.

By making this adjustment, the example now accurately demonstrates the intended functionality of the macro component, ensuring clarity for developers who reference this documentation. This commit closes issue #3841, indicating that the problem has been resolved.

Files changed

  • lib/phoenix_component/macro_component.ex
2025-06-17T11:25:36 See commit

This commit updates the CHANGELOG.md file for the Phoenix LiveView project, incorporating a new addition that highlights the introduction of the :inline_matcher option to Phoenix.LiveView.HTMLFormatter. This option allows developers to configure a list of regular expressions that determine which tag names should be treated as inline elements.

Additionally, the changelog notes other recent changes, such as raising an exception when binding a single DOM element to multiple views, ensuring promise rejections include stack traces, and treating form-associated custom elements as form inputs. Overall, these updates aim to enhance the functionality and robustness of the framework.

Files changed

  • CHANGELOG.md
2025-06-17T13:58:31 See commit

This commit introduces a significant enhancement to the :inline_matcher option in the Phoenix.LiveView.HTMLFormatter module, allowing it to accept both strings and regular expressions for matching tag names. Previously, the :inline_matcher was limited to a list of regular expressions, which restricted its usability. The update changes the default value from a list of regex patterns (e.g., ~r/link/, ~r/button/) to a list of strings (e.g., "link", "button"), making it more intuitive for developers to specify inline components.

Additionally, the commit modifies the implementation of the inline? function to accommodate the new string matching capability, enhancing the flexibility of how inline elements are identified. This change not only simplifies the configuration process for developers but also maintains backward compatibility with existing regular expression patterns, ensuring a smooth transition for users upgrading to the latest version. Overall, this commit improves the functionality and usability of the HTML formatter in Phoenix LiveView.

Files changed

  • CHANGELOG.md
  • lib/phoenix_live_view/html_formatter.ex
2025-06-17T15:36:58 See commit

This commit addresses formatting issues related to backticks in the documentation comments within the Phoenix.LiveView module. Specifically, it modifies two files: engine.ex and html_formatter.ex, correcting the syntax for the documentation links to ensure proper rendering. In engine.ex, the reference to the :key attribute when using :for is updated for clarity, while in html_formatter.ex, the formatting of the inline matcher documentation is similarly corrected.

Overall, the changes enhance the readability and accuracy of the documentation, ensuring that users can easily understand and navigate the references provided in the comments. These adjustments contribute to maintaining high standards for code documentation within the Phoenix framework.

Files changed

  • lib/phoenix_live_view/engine.ex
  • lib/phoenix_live_view/html_formatter.ex