This page covers Elm 0.18

Subscriptions

In Elm, using subscriptions is how your application can listen for external input. Some examples are:

• Keyboard events
• Mouse movements
• Browser locations changes
• Websocket events

To illustrate this, let's create an application that responds to both keyboard and mouse events.

First, install the required libraries:

elm package install elm-lang/mouse
elm package install elm-lang/keyboard

Then, create this program:

module Main exposing (..)

import Html exposing (Html, div, text, program)
import Mouse
import Keyboard


-- MODEL


type alias Model =
    Int


init : ( Model, Cmd Msg )
init =
    ( 0, Cmd.none )



-- MESSAGES


type Msg
    = MouseMsg Mouse.Position
    | KeyMsg Keyboard.KeyCode



-- VIEW


view : Model -> Html Msg
view model =
    div []
        [ text (toString model) ]



-- UPDATE


update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        MouseMsg position ->
            ( model + 1, Cmd.none )

        KeyMsg code ->
            ( model + 2, Cmd.none )



-- SUBSCRIPTIONS


subscriptions : Model -> Sub Msg
subscriptions model =
    Sub.batch
        [ Mouse.clicks MouseMsg
        , Keyboard.downs KeyMsg
        ]



-- MAIN


main : Program Never Model Msg
main =
    program
        { init = init
        , view = view
        , update = update
        , subscriptions = subscriptions
        }

Run this program with Elm reactor. Each time you click the mouse you will see the counter increasing by one; each time you press a key you will see the counter increasing by 2.

Let's review the important parts relevant to subscriptions in this program.

Messages

type Msg
    = MouseMsg Mouse.Position
    | KeyMsg Keyboard.KeyCode

We have two possible messages: MouseMsg and KeyMsg. These will trigger when the mouse or the keyboard are pressed, accordingly.

Update

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        MouseMsg position ->
            ( model + 1, Cmd.none )

        KeyMsg code ->
            ( model + 2, Cmd.none )

Our update function responds to each message differently, so it increases the counter by one when we press the mouse or by two when we press a key.

Subscriptions

subscriptions : Model -> Sub Msg
subscriptions model =
    Sub.batch ➌
        [ Mouse.clicks MouseMsg ➊
        , Keyboard.downs KeyMsg ➋
        ]

Here we declare the things we want to listen to. We want to listen to Mouse.clicks ➊ and Keyboard.downs ➋. Both of these functions take a message constructor and return a subscription.

We use Sub.batch ➌ so we can listen to both of them. batch takes a list of subscriptions and returns one subscription which includes all of them.