You might recognize this diagram from the core Url type documentation:

  https://example.com:8042/over/there?name=ferret#nose
  \___/   \______________/\_________/ \_________/ \__/
    |            |            |            |        |
  scheme     authority       path        query   fragment

AppUrl represents only path + query + fragment:

  https://example.com:8042/over/there?name=ferret#nose
                          \__________________________/
                                        |
                                     AppUrl

That’s the part you’ll work the most with in your app.

An AppUrl is “more parsed“ than Url (where everything is a string):

• path: List String. The path, split by slash. This makes it convenient to pattern match on the segments.
• queryParameters: QueryParameters. A dict of the query parameters, with keys mapped to the values.
• fragment: Maybe String. The fragment, without the leading hash symbol.

Each path segment, query parameter key, query parameter value and the fragment are all percent decoded, so you never need to think about that. For example, %20 is turned into a space and %2F is turned into a slash.

You can think of Url as the type you get from Elm when using Browser.application. From it you can create an AppUrl, and that’s what you’ll use when parsing which page you’re on and when creating links.

Different ways of creating an AppUrl:

• AppUrl.fromUrl

• AppUrl.fromPath

• Create the record directly:

  { path = [ "my", "path" ]
  , queryParameters = Dict.singleton "my" [ "parameter" ]
  , fragment = Just "my-fragment"
  }

A dict of the query parameters, with keys mapped to the values. The same key might be given more than once, so each key is mapped to a list of values.

Get all values of a key:

Dict.get "myParam" url.queryParameters

Get the first value:

Dict.get "myParam" url.queryParameters |> Maybe.andThen List.head

Get the last value:

Dict.get "myParam" url.queryParameters |> Maybe.andThen List.Extra.last

Create query parameters:

Dict.fromList
    [ ( "myRequiredParam", [ "myValue" ] )


    -- Parameters set to the empty list are omitted.
    , ( "myOptionalParam", Maybe.Extra.toList someMaybeString )
    ]

See also choosing a query parameter and query parameter parsing for extra details.

Turn a Url from elm/url into an AppUrl.

This removes one trailing slash from the end of the path (if any), for convenience. For example, /one/two and /one/two/ are both turned into [ "one", "two" ].

Some sites use a trailing slash, some don’t. Users don’t know what to use where. This lets you support both. It’s up to you if you want to update the URL in the location bar of the browser to a canonical version.

Note: You can add an empty string at the end of the path, like [ "one", "two", "" ] if you want to create a string with a trailing slash.

Example:

    AppUrl.fromUrl
        { protocol = Url.Https
        , host = "example.com"
        , port_ = Nothing
        , path = "/my/path"
        , query = Just "my=parameter"
        , fragment = Just "my-fragment"
        }
        --> { path = [ "my", "path" ]
        --  , queryParameters = Dict.singleton "my" [ "parameter" ]
        --  , fragment = Just "my-fragment"
        --  }

Convenience function for creating an AppUrl from just a path, when you don’t need any query parameters or fragment.

It’s nothing more than this helper function:

fromPath : List String -> AppUrl
fromPath path =
    { path = path
    , queryParameters = Dict.empty
    , fragment = Nothing
    }

Example:

AppUrl.fromPath [ "my", "path" ]
--> { path = [ "my", "path" ], queryParameters = Dict.empty, fragment = Nothing }

Turn an AppUrl into a string.

AppUrl.toString
    { path = [ "my", "path" ]
    , queryParameters = Dict.singleton "my" [ "parameter" ]
    , fragment = Just "my-fragment"
    }
    --> "/my/path?my=parameter#my-fragment"

• The string always starts with /.
• It only contains a ? if there are any query parameters.
• Similarly, it only contains a # if there is a fragment.
• Query parameters with the empty string as the value don’t get any equals sign: ?k, not ?k=.
• Query parameters are sorted by key.

Each path segment, query parameter key, query parameter value and the fragment are all percent encoded, but very minimally. See escaping and plus and space for details.

See also Full and relative URLs.