Elm in the Browser

https://package.elm-lang.org/packages/elm/browser/latest/
Admin
This package allows you to create Elm programs that run in browsers, with access to browser history...
Tokens:6,772
Snippets:76
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Elm Browser Package

Source: https://package.elm-lang.org/packages/elm/browser/latest/about

Use the elm install command to add the elm/browser package to your project. This is the first step to using its features for SPAs.

```bash
elm install elm/browser
```

--------------------------------

### Sandbox Program Setup

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser

Use `sandbox` to create a self-contained Elm program. It's ideal for learning the Elm Architecture without external interactions.

```Elm
sandbox :
{
    init : model
    view : model -> Html msg
    update : msg -> model -> model
}
-> Program () model msg
```

--------------------------------

### Application Program Setup

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser

Use `application` to create an Elm program that manages URL changes. It handles initial URL, link clicks, and URL updates.

```Elm
application :
{
    init : flags -> Url -> Key -> ( model, Cmd msg )
    view : model -> Document msg
    update : msg -> model -> ( model, Cmd msg )
    subscriptions : model -> Sub msg
    onUrlRequest : UrlRequest -> msg
    onUrlChange : Url -> msg
}
-> Program flags model msg
```

--------------------------------

### Document Program Setup

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser

Use `document` to create an Elm-managed HTML document. This provides control over both the `<body>` and `<title>` of the page.

```Elm
document :
{
    init : flags -> ( model, Cmd msg )
    view : model -> Document msg
    update : msg -> model -> ( model, Cmd msg )
    subscriptions : model -> Sub msg
}
-> Program flags model msg
```

--------------------------------

### Element Program Setup

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser

Use `element` to create an Elm-managed HTML element. This allows Elm programs to interact with the outside world via commands and subscriptions.

```Elm
element :
{
    init : flags -> ( model, Cmd msg )
    view : model -> Html msg
    update : msg -> model -> ( model, Cmd msg )
    subscriptions : model -> Sub msg
}
-> Program flags model msg
```

--------------------------------

### Get Browser Viewport Information

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Retrieves information about the current browser viewport, including scene and viewport dimensions and scroll positions.

```elm
getViewport : Task x Viewport
getViewport = 
    Browser.Dom.getViewport

```

--------------------------------

### Get Element Position and Dimensions

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Retrieves detailed position and size information for a DOM element specified by its ID. This data includes the element's position relative to the viewport and its dimensions, including margins.

```elm
import Browser.Dom as Dom
import Task

getElement : String -> Task Error Element
getElement id =
    Dom.getElement id

type alias Element =
    {
      scene :
        {
          width : Float,
          height : Float
        },
      viewport :
        {
          x : Float,
          y : Float,
          width : Float,
          height : Float
        },
      element :
        {
          x : Float,
          y : Float,
          width : Float,
          height : Float
        }
    }

```

--------------------------------

### Get Viewport Information of a Specific DOM Node

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Retrieves viewport information for a specific scrollable DOM node identified by its ID. Useful for managing scrollable areas like chat boxes.

```elm
getViewportOf : String -> Task Error Viewport
getViewportOf = 
    Browser.Dom.getViewportOf

```

--------------------------------

### Reset Browser Viewport to Top-Left

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Resets the browser's viewport to the top-left corner (0, 0 offset). Useful for ensuring content starts at the top when navigating between sections or pages within an Elm application.

```elm
import Browser.Dom as Dom
import Task

type Msg
    = NoOp

resetViewport : Cmd Msg
resetViewport =
    Task.perform (\_ -> NoOp) (Dom.setViewport 0 0)

```

--------------------------------

### Window Events

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Events

Subscribe to window events. `onResize` for window size changes and `onVisibilityChange` for tab/window visibility changes.

```APIDOC
## Window Events

### onResize

- **Description**: Subscribe to any changes in window size.
- **Signature**: `onResize : (Int -> Int -> msg) -> Sub msg`

### onVisibilityChange

- **Description**: Subscribe to any visibility changes, like if the user switches to a different tab or window.
- **Signature**: `onVisibilityChange : (Visibility -> msg) -> Sub msg`

### Visibility Type

- **Description**: Value describing whether the page is hidden or visible.
- **Values**: `Visible | Hidden`
```

--------------------------------

### Keyboard Events

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Events

Subscribe to keyboard events. `onKeyPress` for character-producing keys, `onKeyDown` for key down events, and `onKeyUp` for key up events.

```APIDOC
## Keyboard Events

### onKeyPress

- **Description**: Subscribe to key presses that normally produce characters.
- **Signature**: `onKeyPress : Decoder msg -> Sub msg`

### onKeyDown

- **Description**: Subscribe to get codes whenever a key goes down.
- **Signature**: `onKeyDown : Decoder msg -> Sub msg`

### onKeyUp

- **Description**: Subscribe to get codes whenever a key goes up.
- **Signature**: `onKeyUp : Decoder msg -> Sub msg`
```

--------------------------------

### Subscribe to Window Resize Events

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Events

Subscribe to changes in window size. This is equivalent to listening to the window.onresize event in JavaScript.

```Elm
import Browser.Events as E

type Msg
  = GotNewWidth Int

subscriptions : model -> Cmd Msg
subscriptions _ =
  E.onResize (\w h -> GotNewWidth w)
```

--------------------------------

### Navigate to Elm Website

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Navigation

This snippet demonstrates how to use the `load` function to navigate to an external URL, which always results in a page load.

```Elm
gotoElmWebsite : Cmd msg
gotoElmWebsite =
    load "https://elm-lang.org"

```

--------------------------------

### Mouse Events

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Events

Subscribe to mouse events. Includes clicks, mouse movements, mouse down, and mouse up events.

```APIDOC
## Mouse Events

### onClick

- **Description**: Subscribe to mouse clicks anywhere on screen.
- **Signature**: `onClick : Decoder msg -> Sub msg`

### onMouseMove

- **Description**: Subscribe to mouse moves anywhere on screen. Unsubscribe if not needed.
- **Signature**: `onMouseMove : Decoder msg -> Sub msg`

### onMouseDown

- **Description**: Subscribe to get mouse information whenever the mouse button goes down.
- **Signature**: `onMouseDown : Decoder msg -> Sub msg`

### onMouseUp

- **Description**: Subscribe to get mouse information whenever the mouse button goes up.
- **Signature**: `onMouseUp : Decoder msg -> Sub msg`
```

--------------------------------

### back

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Navigation

Navigates the browser back a specified number of pages in the history that the application controls. If the requested number of pages exceeds the application's history, it navigates to the earliest controlled history entry.

```APIDOC
## back

### Description
Goes back a specified number of pages in the browser history managed by the application.

### Method
`back`

### Parameters
#### Path Parameters
- **key** (Key) - Required - A navigation Key obtained from `Browser.application`.
- **count** (Int) - Required - The number of pages to go back.

### Notes
This function only manages the history created by the application. Going back farther than the application's history will navigate to a previously visited external page.
```

--------------------------------

### load

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Navigation

Causes a full page load to the specified URL. This function is used to navigate to a different page entirely, whether it's within the same application or an external website.

```APIDOC
## load

### Description
Leaves the current page and loads the given URL. This always results in a page load.

### Method
`load`

### Parameters
#### Path Parameters
- **url** (String) - Required - The URL to load.

### Example
```elm
gotoElmWebsite : Cmd msg
gotoElmWebsite =
    load "https://elm-lang.org"
```
```

--------------------------------

### Animation Frame Events

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Events

Subscribe to animation frame events for smooth animations. `onAnimationFrame` provides the POSIX time, while `onAnimationFrameDelta` provides the time delta since the previous frame.

```APIDOC
## Animation Frame Events

### onAnimationFrame

- **Description**: Subscribe to animation frame events. Provides the POSIX time on each frame.
- **Signature**: `onAnimationFrame : (Posix -> msg) -> Sub msg`

### onAnimationFrameDelta

- **Description**: Subscribe to animation frame events. Provides the time in milliseconds since the previous frame.
- **Signature**: `onAnimationFrameDelta : (Float -> msg) -> Sub msg`
```

--------------------------------

### reloadAndSkipCache

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Navigation

Reloads the current page without using the browser's cache, ensuring that all resources are fetched fresh. This always results in a page load.

```APIDOC
## reloadAndSkipCache

### Description
Reloads the current page without using the browser cache. This always results in a page load!

### Method
`reloadAndSkipCache`
```

--------------------------------

### Subscribe to Mouse Clicks

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Events

Subscribe to mouse clicks anywhere on the screen. Useful for implementing custom dropdowns or detecting clicks outside an element.

```Elm
import Browser.Events as Events
import Json.Decode as D

type Msg
   = ClickOut

subscriptions : Model -> Sub Msg
subscriptions model =
  case model.dropDown of
    Closed _ ->
      Sub.none

    Open _ ->
      Events.onClick (D.succeed ClickOut)
```

--------------------------------

### getElement

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Retrieves position and size information about a specific DOM element by its ID. Useful for scrolling and drag-and-drop interactions.

```APIDOC
## getElement

### Description
Retrieves position and size information about a specific DOM element by its ID. This information can be used for precise scrolling or drag-and-drop functionality.

### Method
`getElement`

### Parameters
- `id` (String) - The ID of the DOM element to query.

### Response
#### Success Response
- `scene` (Object) - Information about the overall scene.
  - `width` (Float) - The width of the scene.
  - `height` (Float) - The height of the scene.
- `viewport` (Object) - Information about the current viewport.
  - `x` (Float) - The x-offset of the viewport.
  - `y` (Float) - The y-offset of the viewport.
  - `width` (Float) - The width of the viewport.
  - `height` (Float) - The height of the viewport.
- `element` (Object) - Information about the target element.
  - `x` (Float) - The x-coordinate of the element's top-left corner relative to the scene.
  - `y` (Float) - The y-coordinate of the element's top-left corner relative to the scene.
  - `width` (Float) - The width of the element (including margins).
  - `height` (Float) - The height of the element (including margins).

### Example Usage
```elm
import Browser.Dom as Dom
import Task

getPosition : String -> Task Error Dom.Element
getPosition id = 
    Dom.getElement id
```

**Note:** The element's `width` and `height` include its margins, similar to JavaScript's `getBoundingClientRect`.
```

--------------------------------

### Handling Internal and External URL Requests

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser

This snippet demonstrates how to process `UrlRequest` messages within an Elm application's `update` function. It distinguishes between `Internal` and `External` URLs to apply different navigation strategies, such as using `Nav.pushUrl` for internal links and `Nav.load` for external ones. This allows for customized behavior based on the link type.

```elm
import Browser exposing (..)
import Browser.Navigation as Nav
import Url

type Msg
    = ClickedLink UrlRequest

update : Msg -> Model -> ( Model, Cmd msg )
update msg model =
    case msg of
        ClickedLink urlRequest ->
            case urlRequest of
                Internal url ->
                    (
                    model
                    ,
                    Nav.pushUrl model.key (Url.toString url)
                    )

                External url ->
                    (
                    model
                    ,
                    Nav.load url
                    )


```

--------------------------------

### forward

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Navigation

Navigates the browser forward a specified number of pages in the history that the application controls. If there are no more pages in the future history, this function does nothing.

```APIDOC
## forward

### Description
Goes forward a specified number of pages in the browser history managed by the application.

### Method
`forward`

### Parameters
#### Path Parameters
- **key** (Key) - Required - A navigation Key obtained from `Browser.application`.
- **count** (Int) - Required - The number of pages to go forward.

### Notes
This function only manages the history created by the application. Going forward beyond the application's history will navigate to the next page the user visited.
```

--------------------------------

### setViewport

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Changes the x and y offset of the browser viewport immediately. This can be used to scroll the page to a specific position.

```APIDOC
## setViewport

### Description
Changes the `x` and `y` offset of the browser viewport immediately. This can be used to scroll the page to a specific position.

### Method
`setViewport`

### Parameters
- `x` (Float) - The desired x-offset for the viewport.
- `y` (Float) - The desired y-offset for the viewport.

### Example Usage
```elm
import Browser.Dom as Dom
import Task

resetViewport : Cmd msg
resetViewport = 
    Task.perform (\_ -> ...) (Dom.setViewport 0 0)
```
```

--------------------------------

### Viewport Information

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Functions to retrieve information about the browser's viewport and scrollable DOM nodes.

```APIDOC
## getViewport

### Description
Get information on the current viewport of the browser.

### Method
`getViewport : Task x Viewport
`

### Response
#### Success Response
- **Viewport** - An object containing scene and viewport dimensions and position.
  - **scene.width** (float) - The total width of the scrollable content.
  - **scene.height** (float) - The total height of the scrollable content.
  - **viewport.x** (float) - The horizontal scroll position.
  - **viewport.y** (float) - The vertical scroll position.
  - **viewport.width** (float) - The visible width of the viewport.
  - **viewport.height** (float) - The visible height of the viewport.

## getViewportOf

### Description
Get viewport information for a specific scrollable DOM node identified by its ID.

### Method
`getViewportOf : String -> Task Error Viewport
`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the scrollable DOM node.

### Response
#### Success Response
- **Viewport** - An object containing scene and viewport dimensions and position for the specified node.
  - **scene.width** (float) - The total width of the scrollable content.
  - **scene.height** (float) - The total height of the scrollable content.
  - **viewport.x** (float) - The horizontal scroll position.
  - **viewport.y** (float) - The vertical scroll position.
  - **viewport.width** (float) - The visible width of the viewport.
  - **viewport.height** (float) - The visible height of the viewport.

### Error Handling
- **NotFound String** - If the provided ID does not correspond to any DOM node.
```

--------------------------------

### Focus an Input Element

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Finds a DOM node by its ID and sets focus to it. This function fails silently if the ID is not found.

```elm
import Browser.Dom as Dom
import Task

type Msg
    = NoOp

focusSearchBox : Cmd Msg
focusSearchBox = 
    Task.attempt (\_ -> NoOp) (Dom.focus "search-box")

```

--------------------------------

### pushUrl

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Navigation

Changes the browser's URL and adds a new entry to the history without triggering a page load. This is useful for single-page applications to update the address bar as the user interacts with the application.

```APIDOC
## pushUrl

### Description
Changes the URL, but does not trigger a page load. This will add a new entry to the browser history.

### Method
`pushUrl`

### Parameters
#### Path Parameters
- **key** (Key) - Required - A navigation Key obtained from `Browser.application`.
- **url** (String) - Required - The new URL to navigate to.

### Notes
If the user has navigated back and there are future history entries, adding a new URL will clear those future entries.
```

--------------------------------

### reload

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Navigation

Reloads the current page, which always results in a page load. This function may utilize the browser's cache for resources.

```APIDOC
## reload

### Description
Reloads the current page. This always results in a page load!

### Method
`reload`
```

--------------------------------

### replaceUrl

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Navigation

Changes the browser's URL without triggering a page load and without adding a new entry to the browser history. This is useful for scenarios like updating URL parameters for search or filters without cluttering the history.

```APIDOC
## replaceUrl

### Description
Changes the URL, but does not trigger a page load. This will not add a new entry to the browser history.

### Method
`replaceUrl`

### Parameters
#### Path Parameters
- **key** (Key) - Required - A navigation Key obtained from `Browser.application`.
- **url** (String) - Required - The new URL to navigate to.

### Notes
Browsers may rate-limit this function. It can be useful for updating URL parameters without adding history entries for every keystroke.
```

--------------------------------

### Focus and Blur

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Functions to set focus on or remove focus from DOM elements identified by their ID.

```APIDOC
## focus

### Description
Find a DOM node by `id` and focus on it.

### Method
`focus : String -> Task Error ()
`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the DOM node to focus.

### Response
#### Success Response
- **()** - Indicates the operation completed successfully.

### Error Handling
- **NotFound String** - If the provided ID does not correspond to any DOM node.

## blur

### Description
Find a DOM node by `id` and make it lose focus.

### Method
`blur : String -> Task Error ()
`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the DOM node to blur.

### Response
#### Success Response
- **()** - Indicates the operation completed successfully.

### Error Handling
- **NotFound String** - If the provided ID does not correspond to any DOM node.
```

--------------------------------

### Document Type Alias

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser

Defines the structure for an HTML document managed by Elm, including the title and body content.

```Elm
type alias Document msg =
    {
        title : String
        body : List (Html msg)
    }
```

--------------------------------

### UrlRequest Type Definition

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser

Defines the types of URL requests that can occur within an Elm application, distinguishing between internal and external navigation.

```Elm
type UrlRequest
    = Internal Url
    | External String
```

--------------------------------

### Scroll to Bottom of a Specific DOM Element

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Changes the viewport offset of a specific DOM element, identified by its ID, to always show the bottom. This is commonly used in chat or messaging interfaces to keep the latest content visible.

```elm
import Browser.Dom as Dom
import Task

type Msg
    = NoOp

jumpToBottom : String -> Cmd Msg
jumpToBottom id =
    Dom.getViewportOf id
        |> Task.andThen (\_ -> Dom.setViewportOf id 0 info.scene.height)
        |> Task.attempt (\_ -> NoOp)

```

--------------------------------

### setViewportOf

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Changes the x and y offset of a DOM node's viewport by its ID. Useful for keeping the latest message in view in chat applications.

```APIDOC
## setViewportOf

### Description
Changes the `x` and `y` offset of a DOM node's viewport by its ID. This is common in text messaging and chat rooms, where once the messages fill the screen, you want to always be at the very bottom of the message chain.

### Method
`setViewportOf`

### Parameters
- `id` (String) - The ID of the DOM node whose viewport to change.
- `x` (Float) - The desired x-offset for the viewport.
- `y` (Float) - The desired y-offset for the viewport.

### Example Usage
```elm
import Browser.Dom as Dom
import Task

jumpToBottom : String -> Cmd msg
jumpToBottom id = 
    Dom.getViewportOf id
        |> Task.andThen (\info -> Dom.setViewportOf id 0 info.scene.height)
        |> Task.attempt (\_ -> ...)
```

**Note:** The `x` and `y` offsets are clamped to ensure the viewport remains within the scene boundaries.
```

--------------------------------

### Blur an Input Element

Source: https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom

Finds a DOM node by its ID and removes focus from it. This function fails silently if the ID is not found.

```elm
import Browser.Dom as Dom
import Task

type Msg
    = NoOp

unfocusSearchBox : Cmd Msg
unfocusSearchBox = 
    Task.attempt (\_ -> NoOp) (Dom.blur "search-box")

```
Tokens:
Raw