Skip to content

docs: document hooks and JS commands in dead views#4246

Open
SerhiiFesenko wants to merge 2 commits into
phoenixframework:mainfrom
SerhiiFesenko:docs/dead-view-hooks-js-commands
Open

docs: document hooks and JS commands in dead views#4246
SerhiiFesenko wants to merge 2 commits into
phoenixframework:mainfrom
SerhiiFesenko:docs/dead-view-hooks-js-commands

Conversation

@SerhiiFesenko
Copy link
Copy Markdown
Contributor

What

Adds a dedicated, searchable section to the JavaScript interoperability guide covering how phx-hook, phx-mounted, and client-side Phoenix.LiveView.JS commands behave on regular pages that are not LiveViews (dead views).

Why

The term dead view is used broadly across the technical surface — in the code, in the CHANGELOG ("Add dead view support for hooks" / "Add dead view support for JS commands", v0.18.0), and commonly in conversation — but it appears nowhere in the docs. That leaves the term, and the capability behind it, unclear to users who encounter it elsewhere and have nothing to search for.

The feature itself (hooks and JS commands outside a LiveView) shipped in v0.18.0 yet was only hinted at by a single one-line note in the hook lifecycle list that never named "dead view" — so it's effectively undiscoverable, by people and AI assistants alike.

Changes

  • New section "Hooks and JS commands outside of a LiveView" in guides/client/js-interop.md, introducing the term dead view (with synonyms — dead render / static page / outside of a LiveView) and splitting behavior into what works vs. what doesn't:
    • Works: phx-hook (mounted only), phx-mounted, phx-click + purely client-side JS commands.
    • JS.navigate/JS.patch: live navigation when a LiveView is present, otherwise a full-page browser navigation fallback.
    • No effect on a fully static page: JS.push, form bindings (phx-change, phx-submit), phx-connected/phx-disconnected.
  • Cross-reference links added to the phx-mounted and phx-connected/phx-disconnected notes in guides/client/bindings.md.

Docs-only; no code changes.

@SteffenDE
Copy link
Copy Markdown
Collaborator

As per @josevalim, we don't refer to regular views as dead views. Therefore, I don't think we should make this as prominent. So instead of

commonly called dead views (also referred to as dead renders, static pages, or simply markup outside of a LiveView).

rather

(sometimes referred to as dead views, dead renders,
static pages, or simply markup outside of a LiveView).

and then in the headings just say "regular view" instead of "dead view"?

We should also link back to the Phoenix docs (https://hexdocs.pm/phoenix/controllers.html#rendering).

Comment thread guides/client/js-interop.md Outdated
Comment on lines +528 to +529
* **`phx-mounted`** — runs as soon as `liveSocket.connect()` is executed
(see [Bindings](bindings.md#dom-patching)).
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not 100% correct, as we also wait for the document to be ready (i.e. DOMContentLoaded)

if (
["complete", "loaded", "interactive"].indexOf(document.readyState) >= 0
) {
doConnect();
} else {
document.addEventListener("DOMContentLoaded", () => doConnect());
}

@SerhiiFesenko SerhiiFesenko requested a review from SteffenDE May 28, 2026 04:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants