Transmutable.Html.Events

It is often helpful to create an Union Type so you can have many different kinds of events as seen in the TodoMVC example.

Mouse

onClick : msg -> Attribute msg
onDoubleClick : msg -> Attribute msg
onMouseDown : msg -> Attribute msg
onMouseUp : msg -> Attribute msg
onMouseEnter : msg -> Attribute msg
onMouseLeave : msg -> Attribute msg
onMouseOver : msg -> Attribute msg
onMouseOut : msg -> Attribute msg

Forms

onInput : (String -> msg) -> Attribute msg

Detect input events for things like text fields or text areas.

For more details on how onInput works, check out targetValue.

Note 1: It grabs the string value at event.target.value, so it will not work if you need some other information. For example, if you want to track inputs on a range slider, make a custom handler with on.

Note 2: It uses stopPropagationOn internally to always stop propagation of the event. This is important for complicated reasons explained here and here.

onCheck : (Bool -> msg) -> Attribute msg

Detect change events on checkboxes. It will grab the boolean value from event.target.checked on any input event.

Check out targetChecked for more details on how this works.

onSubmit : msg -> Attribute msg

Detect a submit event with preventDefault in order to prevent the form from changing the page’s location. If you need different behavior, create a custom event handler.

Focus

onBlur : msg -> Attribute msg
onFocus : msg -> Attribute msg

Custom

on : String -> Decoder msg -> Attribute msg

Create a custom event listener. Normally this will not be necessary, but you have the power! Here is how onClick is defined for example:

import Json.Decode as Decode

onClick : msg -> Attribute msg
onClick message =
    on "click" (Decode.succeed message)

The first argument is the event name in the same format as with JavaScript's addEventListener function.

The second argument is a JSON decoder. Read more about these here. When an event occurs, the decoder tries to turn the event object into an Elm value. If successful, the value is routed to your update function. In the case of onClick we always just succeed with the given message.

If this is confusing, work through the Elm Architecture Tutorial. It really helps!

Note: This creates a passive event listener, enabling optimizations for touch, scroll, and wheel events in some browsers.

stopPropagationOn : String -> Decoder { message : msg, stopPropagation : Bool } -> Attribute msg

Create an event listener that may stopPropagation. Your decoder must produce a message and a Bool that decides if stopPropagation should be called.

Note: This creates a passive event listener, enabling optimizations for touch, scroll, and wheel events in some browsers.

preventDefaultOn : String -> Decoder { message : msg, preventDefault : Bool } -> Attribute msg

Create an event listener that may preventDefault. Your decoder must produce a message and a Bool that decides if preventDefault should be called.

For example, the onSubmit function in this library always prevents the default behavior:

onSubmit : msg -> Attribute msg
onSubmit msg =
  preventDefaultOn "submit" (Json.map alwaysPreventDefault (Json.succeed msg))

alwaysPreventDefault : msg -> ( msg, Bool )
alwaysPreventDefault msg =
  ( msg, True )
custom : String -> Decoder { message : msg, stopPropagation : Bool, preventDefault : Bool } -> Attribute msg

Create an event listener that may stopPropagation or preventDefault.

Note: Check out the lower-level event API in elm/virtual-dom for more information on exactly how events work, especially the Handler docs.

Custom Decoders

targetValue : Decoder String

A Json.Decoder for grabbing event.target.value. We use this to define onInput as follows:

import Json.Decode as Json

onInput : (String -> msg) -> Attribute msg
onInput tagger =
    stopPropagationOn "input" <|
        Json.map alwaysStop (Json.map tagger targetValue)

alwaysStop : a -> ( a, Bool )
alwaysStop x =
    ( x, True )

You probably will never need this, but hopefully it gives some insights into how to make custom event handlers.

targetChecked : Decoder Bool

A Json.Decoder for grabbing event.target.checked. We use this to define onCheck as follows:

import Json.Decode as Json

onCheck : (Bool -> msg) -> Attribute msg
onCheck tagger =
    on "input" (Json.map tagger targetChecked)
keyCode : Decoder Int

A Json.Decoder for grabbing event.keyCode. This helps you define keyboard listeners like this:

import Json.Decode as Json

onKeyUp : (Int -> msg) -> Attribute msg
onKeyUp tagger =
    on "keyup" (Json.map tagger keyCode)

Note: It looks like the spec is moving away from event.keyCode and towards event.key. Once this is supported in more browsers, we may add helpers here for onKeyUp, onKeyDown, onKeyPress, etc.