Improve layout docs

guides/server/live-layouts.md

@@ -11,8 +11,7 @@ From Phoenix v1.7, your application is made of two layouts:
     in the root layout will remain the same, even as you live navigate
     across LiveViews. The root layout is typically declared on the
     router with `put_root_layout` and defined as "root.html.heex"
-    in your layouts folder. It may also be given via the
-    `:root_layout` option to a `live_session` macro in the router.
+    in your layouts folder
 
   * the app layout - this is the default application layout which
     is rendered on both regular HTTP requests and LiveViews.
@@ -24,17 +23,37 @@ embedded within `MyAppWeb.Layouts`.
 All layouts must call `<%= @inner_content %>` to inject the
 content rendered by the layout.
 
+### Root layout
+
 The "root" layout is rendered only on the initial request and
 therefore it has access to the `@conn` assign. The root layout
 is typically defined in your router:
 
-    plug :put_root_layout, {MyAppWeb.LayoutView, :root}
+    plug :put_root_layout, html: {MyAppWeb.LayoutView, :root}
+
+The root layout can also be set via the `:root_layout` option
+in your router via `Phoenix.LiveView.Router.live_session/2`.
+
+### Application layout
 
 The "app.html.heex" layout is rendered with either `@conn` or
-`@socket`. See the `def controller` and `def live_view` definitions
-in your `MyAppWeb` to learn how it is included.
+`@socket`. Both Controllers and LiveViews explicitly define
+the default layouts they will use. See the `def controller`
+and `def live_view` definitions in your `MyAppWeb` to learn how
+it is included.
+
+For LiveViews, the default layout can be overidden in two different
+ways for flexibility:
+
+  1. The `:layout` option in `Phoenix.LiveView.Router.live_session/2`,
+     when set, will override the `:layout` option given via
+     `use Phoenix.LiveView`
+
+  2. The `:layout` option returned on mount, via `{ok, socket, layout: ...}`
+     will override any previously set layout option
 
-*Note*: The live layout is always wrapped by the LiveView's `:container` tag.
+The LiveView itself will be rendered inside the layout wrapped by
+the `:container` tag.
 
 ## Updating the HTML document title
 

lib/phoenix_live_view.ex

@@ -343,7 +343,9 @@ defmodule Phoenix.LiveView do
       the value is reset, it won't be re-rendered again until it is explicitly
       assigned
 
-    * `:layout` - the optional layout to be used by the LiveView
+    * `:layout` - the optional layout to be used by the LiveView. Setting
+      this option will override any layout previously set via
+      `Phoenix.LiveView.Router.live_session/2` or on `use Phoenix.LiveView`
 
   """
   @callback mount(
@@ -457,12 +459,19 @@ defmodule Phoenix.LiveView do
 
   ## Options
 
-    * `:namespace` - configures the namespace the `LiveView` is in
     * `:container` - configures the container the `LiveView` will be wrapped in
-    * `:layout` - configures the layout the `LiveView` will be rendered in
-    * `:log` - configures the log level for the `LiveView`
+
     * `:global_prefixes` - the global prefixes to use for components. See
       `Global Attributes` in `Phoenix.Component` for more information.
+
+    * `:layout` - configures the layout the `LiveView` will be rendered in.
+      This layout can be overridden by on `c:mount/3` or via the `:layout`
+      option in `Phoenix.LiveView.Router.live_session/2`
+
+    * `:log` - configures the log level for the `LiveView`
+
+    * `:namespace` - configures the namespace the `LiveView` is in
+
   """
   defmacro __using__(opts) do
     # Expand layout if possible to avoid compile-time dependencies

lib/phoenix_live_view/router.ex

@@ -143,7 +143,10 @@ defmodule Phoenix.LiveView.Router do
       each LiveView in the session_. See `Phoenix.LiveView.on_mount/1`. Passing a
       single value is also accepted.
 
-    * `:layout` - The optional layout the LiveView will be rendered in.
+    * `:layout` - The optional layout the LiveView will be rendered in. Setting
+      this option overrides the layout via `use Phoenix.LiveView`. This option
+      may be overridden inside a LiveView by returning `{:ok, socket, layout: ...}`
+      from the mount callback
 
   ## Examples