Surprising HEEx @rest defaults

Default values can get surprisingly tricky when dealing with @rest (aka :global) attributes. It's best to avoid this and use dedicated attributes. But if you're stuck in this spot, let's explore the subtle gothas in this post.

The Problem with Default Values and @rest

Imagine you're building an <.input /> component that should have a default value phx-debounce="blur", but also allow users to:

Override it with a different value like phx-debounce="100"
Explicitly set it to nil to remove the attribute entirely

Here's the catch: the order and method of defining default values with @rest matters! And it's not what you would expect.

Let's explore this with a simple example:

Different Approaches to Default Values

Let's examine five different approaches and their behavior:

Approach	No Override	Override to "100"	Override to nil
Dedicated attr with default	✅ blur	✅ 100	✅ nil
Default before @rest naive	✅ blur	❌ blur	❌ blur
Default after @rest naive	✅ blur	✅ 100	❌ blur
Default before @rest conditional	✅ blur	✅ 100	✅ nil
Default after @rest conditional	✅ blur	✅ 100	✅ nil

The Implementations Behind Each Approach

Let's look at each implementation to understand why they behave differently:

Full Example

I've created a single-file Phoenix app to demonstrate all these scenarios. You can run it with elixir app.exs and see the results for yourself:

app.exs

Application.put_env(:sample, Example.Endpoint,
  http: [ip: {127, 0, 0, 1}, port: 5001],
  server: true,
  live_view: [signing_salt: "aaaaaaaa"],
  secret_key_base: String.duplicate("a", 64)
)

Mix.install(
  [
    {:plug_cowboy, "~> 2.5"},
    {:jason, "~> 1.0"},
    {:phoenix, "~> 1.7"},
    # please test your issue using the latest version of LV from GitHub!
    {:phoenix_live_view,
     github: "phoenixframework/phoenix_live_view", branch: "main", override: true}
  ]
)

# if you're trying to test a specific LV commit, it may be necessary to manually build
# the JS assets. To do this, uncomment the following lines:
# this needs mix and npm available in your path!
#
# path = Phoenix.LiveView.__info__(:compile)[:source] |> Path.dirname() |> Path.join("../")
# System.cmd("mix", ["deps.get"], cd: path, into: IO.binstream())
# System.cmd("npm", ["install"], cd: Path.join(path, "./assets"), into: IO.binstream())
# System.cmd("mix", ["assets.build"], cd: path, into: IO.binstream())

defmodule Example.ErrorView do
  def render(template, _), do: Phoenix.Controller.status_message_from_template(template)
end

defmodule Example.Components do
  use Phoenix.Component

  attr :expected, :string
  attr :"phx-debounce", :string, default: "blur"
  def dedicated_attr_with_default(assigns) do
    ~H"""
    <input
      phx-debounce={assigns[:"phx-debounce"]}
      data-expected={@expected}
    />
    """
  end

  attr :expected, :string
  attr :rest, :global
  def before_rest_naive(assigns) do
    ~H"""
    <input
      phx-debounce="blur"
      {@rest}
      data-expected={@expected}
    />
    """
  end

  attr :expected, :string
  attr :rest, :global
  def after_rest_naive(assigns) do
    ~H"""
    <input
      {@rest}
      phx-debounce="blur"
      data-expected={@expected}
    />
    """
  end

  attr :expected, :string
  attr :rest, :global
  def before_rest_conditional(assigns) do
    ~H"""
    <input
      phx-debounce={if not Map.has_key?(@rest, :"phx-debounce"), do: "blur"}
      {@rest}
      data-expected={@expected}
    />
    """
  end

  attr :expected, :string
  attr :rest, :global
  def after_rest_conditional(assigns) do
    ~H"""
    <input
      {@rest}
      phx-debounce={if not Map.has_key?(@rest, :"phx-debounce"), do: "blur"}
      data-expected={@expected}
    />
    """
  end
end

defmodule Example.HomeLive do
  use Phoenix.LiveView, layout: {__MODULE__, :live}

  def mount(_params, _session, socket) do
    {:ok, assign(socket, :count, 0)}
  end

  def render("live.html", assigns) do
    ~H"""
    <script src="/assets/phoenix/phoenix.js">
    </script>
    <script src="/assets/phoenix_live_view/phoenix_live_view.js">
    </script>
    <%!-- uncomment to use enable tailwind --%>
    <%!-- <script src="https://cdn.tailwindcss.com"></script> --%>
    <script>
      let liveSocket = new window.LiveView.LiveSocket("/live", window.Phoenix.Socket)
      liveSocket.connect()
    </script>
    <style>
      * { font-size: 16px; }
    </style>
    {@inner_content}
    """
  end

  def render(assigns) do
    ~H"""
    <script>
      document.addEventListener('DOMContentLoaded', function() {
        document.querySelectorAll('input').forEach(input => {
          const value = input.getAttribute('phx-debounce')
          const expected = input.getAttribute('data-expected')
            console.log(value, expected)
          input.outerHTML += `<br/>${value == expected && "✅" || "❌"} phx-debounce = ${value}`
        })
      })
    </script>
    <table id="table" phx-update="ignore">
      <tr>
        <th></th>
        <th>No override</th>
        <th>Override phx-debounce="100"</th>
        <th>Override phx-debounce="nil"</th>
      </tr>

      <tr>
        <td>Dedicated attr with default</td>
        <td><Example.Components.dedicated_attr_with_default expected="blur" /></td>
        <td><Example.Components.dedicated_attr_with_default phx-debounce="100" expected="100" /></td>
        <td><Example.Components.dedicated_attr_with_default phx-debounce={nil} expected={nil} /></td>
      </tr>

      <tr>
        <td>Default before @rest naive</td>
        <td><Example.Components.before_rest_naive expected="blur" /></td>
        <td><Example.Components.before_rest_naive phx-debounce="100" expected="100" /></td>
        <td><Example.Components.before_rest_naive phx-debounce={nil} expected={nil} /></td>
      </tr>

      <tr>
        <td>Default after @rest naive</td>
        <td><Example.Components.before_rest_naive expected="blur" /></td>
        <td><Example.Components.after_rest_naive phx-debounce="100" expected="100" /></td>
        <td><Example.Components.after_rest_naive phx-debounce={nil} expected={nil} /></td>
      </tr>

      <tr>
        <td>Default before @rest conditional</td>
        <td><Example.Components.before_rest_conditional expected="blur"/></td>
        <td><Example.Components.before_rest_conditional phx-debounce="100" expected="100" /></td>
        <td><Example.Components.before_rest_conditional phx-debounce={nil} expected={nil} /></td>
      </tr>

      <tr>
        <td>Default after @rest conditional</td>
        <td><Example.Components.before_rest_conditional expected="blur" /></td>
        <td><Example.Components.after_rest_conditional phx-debounce="100" expected="100" /></td>
        <td><Example.Components.after_rest_conditional phx-debounce={nil} expected={nil} /></td>
      </tr>
    </table>
    """
  end
end

defmodule Example.Router do
  use Phoenix.Router
  import Phoenix.LiveView.Router

  pipeline :browser do
    plug(:accepts, ["html"])
  end

  scope "/", Example do
    pipe_through(:browser)

    live("/", HomeLive, :index)
  end
end

defmodule Example.Endpoint do
  use Phoenix.Endpoint, otp_app: :sample
  socket("/live", Phoenix.LiveView.Socket)

  plug Plug.Static, from: {:phoenix, "priv/static"}, at: "/assets/phoenix"
  plug Plug.Static, from: {:phoenix_live_view, "priv/static"}, at: "/assets/phoenix_live_view"

  plug(Example.Router)
end

{:ok, _} = Supervisor.start_link([Example.Endpoint], strategy: :one_for_one)
Process.sleep(:infinity)

Dedicated Attribute with Default

attr :"phx-debounce", :string, default: "blur"
def dedicated_attr_with_default(assigns) do
  ~H"""
  <input
    phx-debounce={assigns[:"phx-debounce"]}
  />
  """
end

This works perfectly because Phoenix's attribute system handles the default value for us.

Default Before @rest (Naive)

attr :rest, :global
def before_rest_naive(assigns) do
  ~H"""
  <input
    phx-debounce="blur"
    {@rest}
  />
  """
end

You would expect a custom override in @rest to win over the default, because {@rest} comes last (last value wins). But it does not! The default value always wins. We can neither override to "100" nor can we remove by setting to nil.

Default After @rest (Naive)

attr :rest, :global
def after_rest_naive(assigns) do
  ~H"""
  <input
    {@rest}
    phx-debounce="blur"
  />
  """
end

This works when overriding with a value but fails with nil.

Default Before @rest (Conditional)

attr :rest, :global
def before_rest_conditional(assigns) do
  ~H"""
  <input
    phx-debounce={if not Map.has_key?(@rest, :"phx-debounce"), do: "blur"}
    {@rest}
  />
  """
end

This works in all cases! We only apply the default if the key isn't present in @rest. Then @rest is applied, potentially including explicit nil values.

Default After @rest (Conditional)

attr :rest, :global
def after_rest_conditional(assigns) do
  ~H"""
  <input
    {@rest}
    phx-debounce={if not Map.has_key?(@rest, :"phx-debounce"), do: "blur"}
  />
  """
end

This also works correctly - we first apply @rest, then conditionally add our default only if needed. So if using the conditional approach, order doesn't matter.

Key Learnings

From our experiments, we can derive some important principles:

Order matters with @rest:
- Defaults should be placed after {@rest} - this is surprising!
Apply the default conditionally:
- To allow overriding with nil, only apply the default if not Map.has_key?(@rest, :attr_name)
- If you're using this approach, order does not matter after all.
Prefer dedicated attributes:
- The problem does not arise if you use a dedicated attr :name, default: :default