mouseleave event not triggered/available

[ygoe]

mapbox-gl-js version: latest

browser: all

This will not be called when the mouse cursor leaves the map on the page:

map.on("mouseleave", e => console.log("mouseleave event"));

No error is shown either.

I only found a related issue #4772 that has interesting links. The documentation says (somewhere far down) that the "mouseleave" event can only be subscribed for single layers, but it should also fire when the mouse leaves the map canvas altogether.

Now I need exactly the second part of the description. I don't care about layers, I don't even know (yet) what they are. I need an event when the mouse is no longer over the map canvas.

I'm not sure if this is a technical limitation or what the cause is. I'm just wondering why that event was missed out. Everything else works fine, but not this one.

Workaround

Don't use the on method for this event but fall back to the good old addEventListener on the map's DOM element. That call will stick out from the others and definitely needs explanation in my source code.

mapContainer.addEventListener("mouseleave", e => ...);

A more complete example of this can be found in my workaround code for another issue.

[rreusser]

Hi, @ygoe. Unless there's a specific reason why your workaround doesn't work, I think it's actually the appropriate solution in this case. Events on the map instance are a bit different in that they pertain to specific features (contained in layers) on the map. So that you might, for example, listen to mouseover events on a road or mouseleave events on a body of water. The mouseleave event will also fire if the mouse leaves the map, but if your goal is only an event when the mouse leaves the DOM element, then listening for that event on the map instance rather than the DOM element brings in map-specific context that you probably don't want.

See for example: Create a hover effect.

[ygoe]

I've seen that example but it didn't show what I wanted to do.

Alright, I understand that map.on is meant to be used with map features only (or primarily, at least). I've changed my code to only use DOM event handlers (also saves me the additional .originalEvent). Seems to work fine on my devices. Probably nothing more to do here.

[ryanhamley]

@ygoe You can use the mouseout event to achieve this, rather than mouseleave. I think we may need to update the documentation for mouseleave.

map.on('mouseout', function () {
    console.log('mouseevent happens');
});

[rreusser]

Thanks for catching that, @ryanhamley, and apologies I missed the mouseout event, @ygoe! I've submitted a PR for the docs to make the behavior of mouseleave and its relation to mouseout extra clear: #10598

[ygoe]

I looked up the difference between mouseout and mouseleave on MDN and found that mouseleave is the more robust one that I need to use. mouseout can lead to unexpected behaviour. Anyway, the DOM functions work fine now.