{"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":"python","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,"search_vec":"'2.0.4':56 '3':59 'ad':32 'addit':72 'arbitrari':45 'captur':18 'click':40 'compat':66 'current':53 'custom':2,15 'driven':64 'enabl':31 'environ':51 'event':9,24,47,75 'featur':34,71 'frontend':78 'handl':44 'imag':42 'interact':33,79 'ipyev':12 'ipywidget':74 'jupyt':26,50,73 'jupyterlab':58,68 'keyboard':8,23,36,77 'like':35 'mous':6,21,76 'mouse/keyboard':46 'provid':13 'python':11,29 'react':38 'releas':62 'return':5,20 'shortcut':37 'target':57 'version':54,69 'widget':3,16,27 'within':48","created_at":"2026-04-15T18:38:22.616839+00:00","updated_at":"2026-04-16T15:47:30.037845+00:00","problems":[{"fix":"Ensure `ipyevents` is installed and the JupyterLab extension is correctly linked. For `ipyevents` 2.0.0+ with JupyterLab 3+, `pip install ipyevents` should be sufficient, as it automatically handles the lab extension. If issues persist, try `jupyter labextension install @jupyter-widgets/jupyterlab-manager ipyevents` and restart JupyterLab.","cause":"This error typically occurs when the `ipyevents` JupyterLab extension is not correctly installed or enabled, or if there's a version mismatch between `ipyevents` and JupyterLab (especially when using ipyevents versions < 2.0.0 with JupyterLab 3+).","error":"Module ipyevents, semver range X.Y.Z is not registered as a widget module"},{"fix":"Install the package using pip: `pip install ipyevents`. If using Anaconda, ensure it's installed in the correct environment or try `conda install -c conda-forge ipyevents`. After installation, restart your Jupyter kernel.","cause":"The `ipyevents` package is not installed in the Python environment currently being used by your Jupyter kernel, or the kernel's environment does not match where `ipyevents` was installed.","error":"ModuleNotFoundError: No module named 'ipyevents'"},{"fix":"Ensure the widget linked as the `source` for `ipyevents.Event` has focus (e.g., by clicking on it) in the Jupyter interface. Be aware that once `ipyevents` captures a keyboard event, it will not be processed by the notebook itself.","cause":"For `ipyevents` to capture keyboard events, the `Event` widget needs to have focus in the browser. Additionally, when `ipyevents` captures keyboard events, it intentionally prevents them from propagating further to the notebook to avoid unintended actions.","error":"Keyboard events (e.g., keydown) are not firing or not propagating to Python."},{"fix":"Update `jupyterlab`, `ipywidgets`, and `jupyterlab-widgets` to their latest compatible versions: `pip install -U jupyterlab ipywidgets jupyterlab-widgets`. Clearing your browser cache and restarting JupyterLab might also resolve the issue.","cause":"This is a generic error often indicating a problem with Jupyter widgets, which `ipyevents` is built upon. It can be due to corrupted installations, outdated `ipywidgets` or `jupyterlab-widgets` packages, or a mismatch in versions between the Python backend and the JavaScript frontend.","error":"Error displaying widget"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.0.4","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/mwcraig/ipyevents","docs":null,"changelog":null,"pypi":"https://pypi.org/project/ipyevents/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}