Browser.Events

In JavaScript, information about the root of an HTML document is held in the document and window objects. This module lets you create event listeners on those objects for the following topics: animation, keyboard, mouse, and window.

If there is something else you need, use ports to do it in JavaScript!

Animation

onAnimationFrame : (Posix -> msg) -> Sub msg

An animation frame triggers about 60 times per second. Get the POSIX time on each frame. (See gren-lang/time for more info on POSIX times.)

Note: Browsers have their own render loop, repainting things as fast as possible. If you want smooth animations in your application, it is helpful to sync up with the browsers natural refresh rate. This hooks into JavaScript's requestAnimationFrame function.

onAnimationFrameDelta : (Float -> msg) -> Sub msg

Just like onAnimationFrame, except message is the time in milliseconds since the previous frame. So you should get a sequence of values all around 1000 / 60 which is nice for stepping animations by a time delta.

Keyboard

onKeyPress : Decoder msg -> Sub msg

Subscribe to key presses that normally produce characters. So you should not rely on this for arrow keys.

Note: Check out this advice to learn more about decoding key codes. It is more complicated than it should be.

onKeyDown : Decoder msg -> Sub msg

Subscribe to get codes whenever a key goes down. This can be useful for creating games. Maybe you want to know if people are pressing w, a, s, or d at any given time.

Note: Check out this advice to learn more about decoding key codes. It is more complicated than it should be.

onKeyUp : Decoder msg -> Sub msg

Subscribe to get codes whenever a key goes up. Often used in combination with onVisibilityChange to be sure keys do not appear to down and never come back up.

Mouse

onClick : Decoder msg -> Sub msg

Subscribe to mouse clicks anywhere on screen. Maybe you need to create a custom drop down. You could listen for clicks when it is open, letting you know if someone clicked out of it:

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)
onMouseMove : Decoder msg -> Sub msg

Subscribe to mouse moves anywhere on screen.

You could use this to implement resizable panels like in Gren's online code editor. Check out the example imprementation here.

Note: Unsubscribe if you do not need these events! Running code on every single mouse movement can be very costly, and it is recommended to only subscribe when absolutely necessary.

onMouseDown : Decoder msg -> Sub msg

Subscribe to get mouse information whenever the mouse button goes down.

onMouseUp : Decoder msg -> Sub msg

Subscribe to get mouse information whenever the mouse button goes up. Often used in combination with onVisibilityChange to be sure keys do not appear to down and never come back up.

Window

onResize : (Int -> Int -> msg) -> Sub msg

Subscribe to any changes in window size.

For example, you could track the current width by saying:

import Browser.Events as E

type Msg
  = GotNewWidth Int

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

Note: This is equivalent to getting events from window.onresize.

onVisibilityChange : (Visibility -> msg) -> Sub msg

Subscribe to any visibility changes, like if the user switches to a different tab or window. When the user looks away, you may want to:

  • Pause a timer.
  • Pause an animation.
  • Pause video or audio.
  • Pause an image carousel.
  • Stop polling a server for new information.
  • Stop waiting for an onKeyUp event.
type Visibility
= Visible
| Hidden

Value describing whether the page is hidden or visible.