Type that get returned by a browser mouse event. Its purpose is to provide all useful properties of JavaScript MouseEvent in the context of the elm programming language.

Coordinates of a specific kind (clientX/Y, pageX/Y, ...) are available under the attribute of the same name grouped by pairs. For example, if mouseEvent is of type Mouse.Event then mouseEvent.clientPos holds the ( clientX, clientY ) properties of the event.

For some applications like drawing in a canvas, relative coordinates are needed. Beware that those coordinates are called offsetX/Y in a mouse event. Therefore they are available here with attribute offsetPos.

relativePos : Mouse.Event -> ( Float, Float )
relativePos mouseEvent =
    mouseEvent.offsetPos

The movementX/Y properties not being compatible with Safari / iOS, they are not provided by this package. The x and y properties being equivalent to clientX/Y, are not provided either. The screenPos attribute provides screenX/Y properties in case needed, but you shall use instead the clientPos attribute when in doubt. screenX/Y values are not given in CSS pixel sizes and thus not very useful. More info is available in the excellent article A tale of two viewports.

The keys that might have been pressed during mouse event. Key modifiers of mouse events are available in the key attribute. Checking if the ctrl key was hold when the event triggered is as easy as:

isCtrlKeyPressed : Mouse.Event -> Bool
isCtrlKeyPressed mouseEvent =
    mouseEvent.keys.ctrl

The button pressed for the event. The button that was used to trigger the mouse event is available in the button attribute. However, beware that its value is not reliable for events such as mouseenter, mouseleave, mouseover, mouseout or mousemove.

The buttons (with an "s") property of a mouse event is not provided here since it is not compatible with mac / safari.

Listen to mousedown events. Let's say that we have a message type like this:

type Msg
    = DownMsg ( Float, Float )
    | MoveMsg ( Float, Float )
    | UpMsg ( Float, Float )

Then we could listen to mousedown events like below:

div
    [ Mouse.onDown (\event -> DownMsg event.clientPos) ]
    [ text "click here" ]

In a curried style, this can also be written:

div
    [ Mouse.onDown (.clientPos >> DownMsg) ]
    [ text "click here" ]

Listen to mousemove events. Similarly than with onDown, we can write something like:

div
    [ Mouse.onMove (.clientPos >> MoveMsg) ]
    [ text "move here" ]

Listen to mouseup events. Similarly than with onDown, we can write something like:

div
    [ Mouse.onUp (.clientPos >> UpMsg) ]
    [ text "click here" ]

Listen to click events.

Listen to dblclick events.

Listen to mouseenter events. This event is fired when a mouse is moved over the element that has the listener attached. It is similar to mouseover but doesn't bubble. More details available on the MDN documentation.

Listen to mouseover events.

Listen to mouseleave events. This event is fired when a mouse is moved out of the element that has the listener attached. It is similar to mouseout but doesn't bubble. More details available on the MDN documentation.

Listen to mouseout events.

Listen to contextmenu events. Fired on right mousedown, before the context menu is displayed.

Options for the event.

Choose the mouse event to listen to, and specify the event options. If for some reason the default behavior of this package (prevent default) does not fit your needs, you can change it with for example:

onDown : (Mouse.Event -> msg) -> Html.Attribute msg
onDown =
    { stopPropagation = False, preventDefault = True }
        |> Mouse.onWithOptions "mousedown"

An Event decoder for mouse events. The decoder is provided so that you can extend Mouse.Event with specific properties you need. If for example you need the movementX/Y properties and you can guaranty that users will not use safari, you could do:

type alias EventWithMovement =
    { mouseEvent : Mouse.Event
    , movement : ( Float, Float )
    }


decodeWithMovement : Decoder EventWithMovement
decodeWithMovement =
    Decode.map2 EventWithMovement
        Mouse.eventDecoder
        movementDecoder


movementDecoder : Decoder ( Float, Float )
movementDecoder =
    Decode.map2 (\a b -> ( a, b ))
        (Decode.field "movementX" Decode.float)
        (Decode.field "movementY" Decode.float)

And use it like follows:

type Msg
    = Movement ( Float, Float )


div
    [ onMove (.movement >> Movement) ]
    [ text "move here" ]




onMove : (EventWithMovement -> msg) -> Html.Attribute msg
onMove tag =
    let
        decoder =
            decodeWithMovement
                |> Decode.map tag
                |> Decode.map options


        options message =
            { message = message
            , stopPropagation = False
            , preventDefault = True
            }
    in
    Html.Events.custom "mousemove" decoder