When to Use Html.Lazy in Elm: A Practical Decision Guide

The decision you're actually making

Every time your Elm model changes, your view function runs again and builds a fresh virtual DOM tree. For most apps this is fine — the diff is cheap and Elm is fast. But once a subtree gets expensive (hundreds of nodes, a chart, a long list with rich rows), recomputing it on every keystroke or timer tick starts to show up as dropped frames.

Elm gives you three tools for this situation: plain Html (the default), Html.Keyed (for reorderable lists), and Html.Lazy (memoized sub-views). They solve different problems, and picking the wrong one either does nothing or introduces subtle staleness bugs. This guide helps you pick, then shows a working example.

Comparing the three options

A common misconception: keyed nodes and lazy nodes are not interchangeable. Keying controls DOM reuse when order changes. Laziness controls view recomputation when the model changes. A sortable table of expensive rows may want both — keyed on the container, lazy on each row.

Rules of thumb for choosing

• Start with plain Html. Only reach for Lazy after you can point at a specific slow subtree, ideally confirmed in the browser's performance panel.
• The lazy view function must be pure in practice: its output must depend only on the arguments you pass. If it reads anything else (a closed-over value that changes), Elm's structural equality check won't see the change and you'll render stale content.
• Pass the smallest possible arguments. lazy renderUser user re-renders when any field of user changes; lazy2 renderAvatar name avatarUrl only re-renders when those two fields change.
• Avoid laziness on views whose inputs change constantly (e.g. anything receiving a ticking clock value) — you pay the comparison and caching overhead and get nothing back.
• Don't apply Lazy everywhere defensively. Each lazy node allocates a cache entry, and a blanket of them makes real regressions harder to spot.

Concrete implementation

Suppose a dashboard re-renders every second because of a clock, but it contains an expensive activity feed that only depends on the list of events. Wrap just the feed:

module Main exposing (..)

import Html exposing (Html, div, text)
import Html.Lazy exposing (lazy)

-- Expensive: renders hundreds of rows
activityFeed : List Event -> Html Msg
activityFeed events =
    div [] (List.map renderEvent events)

view : Model -> Html Msg
view model =
    div []
        [ text ("Time: " ++ model.currentTime)
        , lazy activityFeed model.events
        ]

Now, when model.currentTime updates each second, Elm compares the new model.events with the cached argument, finds them structurally equal, and skips calling activityFeed entirely. The clock text still updates normally.

If Event is a record containing a field you want to ignore (say, a lastFetched timestamp that shouldn't trigger a re-render), structural equality is too strict. Use Html.LazyWith from elm-community/html-extra:

import Html.LazyWith exposing (lazyWith)

eventsEqual : List Event -> List Event -> Bool
eventsEqual a b =
    List.map .id a == List.map .id b

-- in view:
lazyWith eventsEqual activityFeed model.events

Be careful here: this equality ignores everything except IDs, so edits to an event's title will not re-render. Write the equality to compare exactly the fields the view actually displays.

How to verify it works

Assumptions: Elm 0.19.1, compiled with elm make or run via elm reactor. No special permissions are needed; everything below happens in your own project directory and browser.

1. Add a temporary Debug.log "feed rendered" events call inside activityFeed (compile without --optimize, since the optimizer strips Debug).
2. Trigger an update that changes only the clock. With lazy in place, the log should not fire. Replace lazy activityFeed model.events with a plain call and repeat — the log now fires on every tick.
3. For a real measurement rather than a log line, record a trace in your browser's performance panel during a few seconds of ticking and compare scripting time between the two versions.
4. Remove the Debug.log before committing.

Limitations

Laziness only helps when the comparison is cheaper than the render — usually true, but a very large argument list can make structural equality itself noticeable. Cached views also consume memory proportional to how many distinct lazy nodes exist, so lazily wrapping every row of an unbounded list can grow memory without bound. Finally, memoization can mask a performance bug elsewhere: if the UI feels fast only because a subtree is frozen, confirm it actually updates when its data changes. The Debug.log check above doubles as that confirmation.