Skip to content

Commit

Permalink
More guidelines around LiveComponents
Browse files Browse the repository at this point in the history
josevalim committed Jan 22, 2025

Verified

This commit was signed with the committer’s verified signature.
aduh95 Antoine du Hamel
1 parent 604d12e commit 0348030
Showing 3 changed files with 19 additions and 16 deletions.
24 changes: 12 additions & 12 deletions guides/introduction/welcome.md
Original file line number Diff line number Diff line change
@@ -242,13 +242,12 @@ function that receives an assigns map and returns a `~H` template. For example:
end

You can learn more about function components in the `Phoenix.Component`
module. At the end of the day, they are a useful mechanism to reuse markup
in your LiveViews.
module. At the end of the day, they are a useful mechanism for code organization
and to reuse markup in your LiveViews.

However, sometimes you need to compartmentalize or reuse more than just markup.
Perhaps you want to move part of the state or some of the events in your
LiveView to a separate module. For these cases, LiveView provides
`Phoenix.LiveComponent`, which are rendered using
However, sometimes you need to share more than just markup across LiveViews,
and you also need to move events to a separate module. For these cases, LiveView
provide `Phoenix.LiveComponent`, which are rendered using
[`live_component/1`](`Phoenix.Component.live_component/1`):

```heex
@@ -257,9 +256,10 @@ LiveView to a separate module. For these cases, LiveView provides

LiveComponents have their own `mount/1` and `handle_event/3` callbacks, as well
as their own state with change tracking support, similar to LiveViews. They are
lightweight since they "run" in the same process as the parent LiveView.
However, this means an error in a LiveComponent would cause the whole view
to fail to render. For a complete rundown, see `Phoenix.LiveComponent`.
lightweight since they "run" in the same process as the parent LiveView, but
are more complex than function components themselves. Given they all run in the
same process, errors in components cause the whole view to fail to render.
For a complete rundown, see `Phoenix.LiveComponent`.

Finally, if you want complete isolation between parts of a LiveView, you can
always render a LiveView inside another LiveView by calling
@@ -279,9 +279,9 @@ abstraction if all you want is to compartmentalize markup or events (or both).

To sum it up:

* use `Phoenix.Component` to compartmentalize/reuse markup
* use `Phoenix.LiveComponent` to compartmentalize state, markup, and events
* use nested `Phoenix.LiveView` to compartmentalize state, markup, events, and error isolation
* use `Phoenix.Component` for code organization and reusing markup
* use `Phoenix.LiveComponent` for sharing state, markup, and events between LiveViews
* use nested `Phoenix.LiveView` to compartmentalize state, markup, and events (with error isolation)

## Guides

9 changes: 7 additions & 2 deletions lib/phoenix_live_component.ex
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
defmodule Phoenix.LiveComponent do
@moduledoc ~S'''
LiveComponents are a mechanism to compartmentalize state, markup, and
events in LiveView.
events for sharing across LiveViews.
LiveComponents are defined by using `Phoenix.LiveComponent` and are used
by calling `Phoenix.Component.live_component/1` in a parent LiveView.
They run inside the LiveView process but have their own state and
life-cycle. For this reason, they are also often called "stateful components".
This is a contrast to `Phoenix.Component`, also known as "function components",
which are stateless and can only compartmentalize markup.
which are stateless and do not have a life-cycle.
The smallest LiveComponent only needs to define a `c:render/1` function:
@@ -40,6 +40,11 @@ defmodule Phoenix.LiveComponent do
> components, as they are a simpler abstraction, with a smaller surface
> area. The use case for live components only arises when there is a need
> for encapsulating both event handling and additional state.
>
> Similarly, avoid using LiveComponents for code design purposes, where
> their main goal is to organize code, rather than sharing it across
> LiveViews. When it comes to code organization and design, Elixir developers
> prefer to use functions and data structures.
## Life-cycle
2 changes: 0 additions & 2 deletions lib/phoenix_live_view/html_formatter.ex
Original file line number Diff line number Diff line change
@@ -4,8 +4,6 @@ defmodule Phoenix.LiveView.HTMLFormatter do
This is a `mix format` [plugin](https://hexdocs.pm/mix/main/Mix.Tasks.Format.html#module-plugins).
> Note: The HEEx HTML Formatter requires Elixir v1.13.4 or later.
## Setup
Add it as a plugin to your `.formatter.exs` file and make sure to put

0 comments on commit 0348030

Please sign in to comment.