{"id":6681,"library":"ipyevents","title":"A custom widget for returning mouse and keyboard events to Python","description":"ipyevents provides a custom widget for capturing and returning mouse and keyboard events from Jupyter widgets to Python. It enables adding interactive features like keyboard shortcuts, reacting to clicks on images, and handling arbitrary mouse/keyboard events within a Jupyter environment. The current version is 2.0.4, targeting JupyterLab 3 and above. Releases are driven by compatibility with JupyterLab versions and feature additions.","status":"active","version":"2.0.4","language":"en","source_language":"en","source_url":"https://github.com/mwcraig/ipyevents","tags":["jupyter","ipywidgets","events","mouse","keyboard","frontend","interactive"],"install":[{"cmd":"pip install ipyevents","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"ipyevents is built on top of ipywidgets to provide event handling for Jupyter widgets.","package":"ipywidgets"},{"reason":"Requires Python 3.9 or higher.","package":"python","optional":false}],"imports":[{"symbol":"Event","correct":"from ipyevents import Event"}],"quickstart":{"code":"from ipywidgets import Label, HTML, display\nfrom ipyevents import Event\n\nl = Label('Click or type on me!')\nl.layout.border = '2px solid red'\nh = HTML('Event info')\n\nd = Event(source=l, watched_events=['click', 'keydown', 'mouseenter'])\n\ndef handle_event(event):\n    lines = [f'{k}: {v}' for k, v in event.items()]\n    content = '<br>'.join(lines)\n    h.value = content\n\nd.on_dom_event(handle_event)\n\ndisplay(l, h)","lang":"python","description":"This quickstart creates a Label widget and an Event listener attached to it. It watches for 'click', 'keydown', and 'mouseenter' events, displaying event information in an HTML widget. This demonstrates how to capture browser events and process them in Python."},"warnings":[{"fix":"Ensure your ipyevents version matches your JupyterLab version. Upgrade JupyterLab to version 3+ for ipyevents 2.x, or downgrade ipyevents to 0.9.0 or earlier for JupyterLab 2.","message":"ipyevents versions 2.0.0 and higher are only built for JupyterLab 3 and up. If you are using JupyterLab 2, you must use ipyevents version 0.9.0 or earlier.","severity":"breaking","affected_versions":"<2.0.0 (for JupyterLab 3+), >=2.0.0 (for JupyterLab 2)"},{"fix":"Be aware that keyboard input will be directed to the watched widget. This is intended behavior to prevent accidental notebook actions. You can style the focused element (e.g., with a blue border) to make it clear which element has focus.","message":"When watching keyboard events, ipyevents will grab the focus of the browser on the source widget. This prevents key presses from being passed to the notebook's default handlers (e.g., for cell navigation or commands).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Utilize the `throttle_or_debounce` and `wait` parameters of the `Event` widget to limit the rate at which events are passed to Python. 'throttle' is good for `mousemove`/`wheel`, 'debounce' for limiting repeated key strokes or clicks.","message":"High-frequency events like 'mousemove' or 'wheel' can generate a large volume of messages between the frontend and backend, potentially leading to performance issues.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If `prevent_default_action` is critical for 'wheel' events, test thoroughly. Consider alternative approaches or monitor the GitHub issues for a fix. There is no direct workaround mentioned in documentation.","message":"The `prevent_default_action` property may not function correctly for 'wheel' events, meaning the browser's default scroll behavior might still occur.","severity":"gotcha","affected_versions":"Unspecified, reported in Issue #76"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}