Form handling is such a fundamental feature that I think we need to nail down clear, consistent terminology for how Hologram approaches it. It’s one of the most common client-side use cases and probably what trips up LiveView users the most - as discussed in this BlueSky thread. I’m planning a dedicated “Forms” page for the website since good and consistent docs are crucial for good DX.

I totally agree that most developers won’t care about implementation details and just want value={@my_value} to work. That abstraction is perfect for them. However, some developers will want to compare Hologram with other frameworks, and having consistent naming for this pattern will be helpful in discussions and documentation.

Based on the feedback here, I’ll definitely avoid “two-way binding” or “bidirectional binding” since these don’t accurately describe what Hologram does and have historical baggage.

I’m considering these alternatives:

• “Controlled Inputs” - familiar to React developers
• “State-Synchronized Inputs” - descriptive for newcomers
• “Input Synchronization” - focuses on the key benefit

(or “Form Elements” instead of “Inputs”)

The core concept is that Hologram maintains unidirectional data flow while solving the DOM synchronization problem that LiveView can’t address.

What do you think would be the clearest terminology? I want to get this right since it’ll be used throughout the documentation and forum discussions.

Looking at this discussion, I think there’s an important distinction to make about scope and intended use cases that clarifies the architectural differences.

You’re right that Hologram is still a separate stateful system next to the DOM, and that external DOM manipulation (browser plugins, console commands) can create inconsistencies that won’t be corrected until the next reconciliation cycle. That’s a fair technical critique for specific cases that intentionally avoid the intended use through the API.

However, I’d argue this is similar to saying “Linux isn’t secure because you can modify /dev/mem as root” - while technically true, it misses the practical scope of what the system is designed to solve.

Where Hologram Does Prevent Inconsistencies

For user-driven interactions - which represent 99.9% of real web app usage - Hologram genuinely does prevent inconsistencies rather than just correct them:

<input $change="update_name" value={@name} />

def action(:update_name, %{event: %{value: name}}, component) do
  put_state(component, :name, name)
end

This creates a closed synchronous loop:

1. User types → DOM event fires immediately
2. Hologram handler executes in same event loop tick
3. State updates immediately
4. VDOM reconciliation happens immediately

JavaScript’s event loop guarantees that the event handler runs atomically and completely before any other queued tasks can execute. This means the DOM event processing and state update happen in true lock-step, with no inconsistency window where they can diverge.

The Key Architectural Difference

The fundamental issue is that latency creates an unavoidable distributed systems challenge for LiveView:

• LiveView: User input → network roundtrip → server processing → network response → DOM reconciliation (with race conditions, ordering issues, connection failures)
• Hologram: User input → immediate local state update → immediate DOM sync (atomic)

External DOM Manipulation Is An Edge Case

Interestingly, even direct input manipulation demonstrates Hologram’s robustness: if someone does document.getElementById("my-input").value = "hacked" and the input has a $change event handler connected to the state, Hologram reconciles automatically and immediately when the programmatic change occurs.

Yes, someone could do document.getElementById("my-div").innerHTML = "hacked content" as you mentioned and break VDOM synchronization until the next reconciliation cycle - but this is equivalent to:

• Using dangerouslySetInnerHTML in React and complaining about inconsistencies
• Manually editing database files and complaining about corruption
• Writing kernel memory directly and complaining Linux crashed

These break the intended API contract and represent edge cases, not fundamental architectural limitations.

The Real-World Impact

For the scenarios developers actually encounter (form interactions, user events, programmatic state updates through the framework), Hologram’s architecture eliminates the consistency problems that LiveView cannot solve due to network latency.

While no abstraction is perfect when you deliberately bypass it, the practical advantage for intended use cases is significant - as @garrison noted with his example of two-input forms that “literally require hooks” in LiveView but work naturally in Hologram.

When developers use Hologram’s event system as intended, it prevents inconsistencies from occurring. When they bypass this system with direct DOM manipulation, inconsistencies can happen - but that’s breaking the API contract.

So… to sum up… given that DOM event handlers are guaranteed to execute atomically without interruption from other queued JavaScript, I think it’s fair to say the distinction I made earlier that you quoted holds true within the framework’s intended scope of user-driven interactions.

@sreyansjain I need to correct my previous advice about using the dev branch.

I shouldn’t have instructed you to use the head of the dev branch (branch: "dev") because there’s currently some incomplete work on CSRF protection that will probably prevent your app from sending commands properly. And generally you shouldn’t rely on the head of the dev branch either. The framework is actively being developed, so sometimes the dev branch can be in a transitional state.

Instead, use the last “green” commit from the dev branch:

{:hologram, git: "https://github.com/bartblast/hologram.git", ref: "84867a2869fa4f58a01e3849eba3b7525773350d"}

This commit has the two-way data binding improvements I mentioned, but without the breaking CSRF changes that are still in progress. Your original code example should work correctly with this specific commit.

Sorry for the confusion!

PS: original post amended…