New SPA navigation package for Browser.element

Show and Tell
1

I’ve published a small package that gives you SPA-style URL navigation using Browser.element and ports, without needing Browser.application.
I’ve been doing this thing for many apps, so it was time I just made a helper package for myself and whoever might find it useful.

Elm: mpizenberg/elm-url-navigation-port
JS companion (npm): elm-url-navigation-port
Source + example: GitHub

Demo app using this package

Why?

I often recommend staying on Browser.element for its simplicity and better compatibility with external JS libraries and browser extensions. But it doesn’t come with URL navigation built in. This package fills that gap with two ports and a tiny JS companion (~50 lines).

As a bonus, it exposes history.pushState with state objects — something Browser.application doesn’t offer. This enables patterns like multi-step wizards that support the back button without changing the URL.

What it provides

Four navigation patterns:

  1. pushUrl — standard SPA page navigation
  2. pushState — push a state object without changing the URL (great for wizard steps)
  3. back / forward — traverse history by N steps
  4. replaceUrl — cosmetic URL updates without notifying Elm

All URLs go through lydell/elm-app-url, so they’re always same-origin by construction.

The example/ directory has a full working demo with all four patterns. That’s the video demo at the top of this post.

Enjoy!

6 Likes
2

Karma. @lydell

New version 1.1.0 that adds the following function:

{-| Navigate to a URL with a state object, creating a new history entry.

The JS companion calls `history.pushState(state, "", url)` and
notifies Elm with both the new URL and the state. Use this when
you need to attach metadata to a history entry alongside a URL
change (e.g. scroll position, referrer context).

    Nav.pushUrlWithState navCmd
        (AppUrl.fromPath [ "product", "42" ])
        (Encode.object [ ( "scrollY", Encode.int 250 ) ])

-}
pushUrlWithState : CommandPort msg -> AppUrl -> Encode.Value -> Cmd msg
1 Like
3

I do this too, for 2 reasons. One is that Browser.Navigation.Key is opaque which is a problem for testing. The other is that as an element you can decide where the Elm application sits within the overall DOM, and pushing it down a div or 2 helps with virtual-dom/browser plugin conflicts.

2 Likes