Skip to content

Commit

Permalink
More guidelines around LiveComponents
Browse files Browse the repository at this point in the history
  • Loading branch information
josevalim committed Jan 22, 2025
1 parent 604d12e commit 0348030
Show file tree
Hide file tree
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
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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

Expand Down
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:
Expand Down Expand Up @@ -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
Expand Down
2 changes: 0 additions & 2 deletions lib/phoenix_live_view/html_formatter.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 0348030

Please sign in to comment.