Utility functions used in marimo.
Note
This is a community led effort and not actively prioritized by the core marimo team.
pip install moutilsor with uv:
uv add moutils| Widget | Description |
|---|---|
URLHash |
Get and set the URL hash |
URLPath |
Get and set the URL path |
URLInfo |
Read all URL components |
DOMQuery |
Query DOM elements with CSS selectors |
CookieManager |
Get, set, and monitor browser cookies |
StorageItem |
Read/write localStorage or sessionStorage |
Slot |
Render HTML with DOM event handlers |
CopyToClipboard |
Copy text to clipboard with a button |
ShellWidget |
Run terminal commands with live output |
ColorScheme |
Detect dark/light mode preference |
ViewportSize |
Detect window dimensions |
OnlineStatus |
Detect network connectivity |
PageVisibility |
Detect if the browser tab is active |
Geolocation |
Get the user's geographic coordinates |
CameraCapture |
Capture a still image from the webcam |
Notification |
Send browser notifications |
KeyboardShortcut |
Listen for global keyboard shortcuts |
thread_mapprocess_mapinterpreter_map |
Thread/Process/Interpreter mapping |
PrintPageButton |
Button to open the browser print dialog |
print_page() |
Programmatically trigger the browser print dialog |
ScreenshotButton |
Button to capture a DOM element as PNG |
screenshot() |
Programmatically screenshot a DOM element |
Get and set the hash portion of the URL.
from moutils import URLHash
h = URLHash()
h.hash # e.g. "#section-1"Get and set the current URL path.
from moutils import URLPath
p = URLPath()
p.path # e.g. "/notebooks/demo"Read all URL components (protocol, hostname, port, pathname, search, hash, etc.).
from moutils import URLInfo
info = URLInfo()
info.hostname # e.g. "localhost"Query DOM elements using CSS selectors.
from moutils import DOMQuery
q = DOMQuery(selector=".my-class")
q.result # list of matched element dataGet, set, and monitor browser cookies.
from moutils import CookieManager
cm = CookieManager()
cm.cookies # dict of current cookiesRead and write data in the browser's localStorage or sessionStorage.
from moutils import StorageItem
s = StorageItem(key="my-key", storage_type="local")
s.data # stored valueRender HTML content and handle DOM events (mouse, keyboard, form, drag, touch, pointer, scroll, clipboard, animation).
from moutils import Slot
s = Slot(children="<button>Click me</button>", on_dblclick=lambda e: print(e))Copy text to the clipboard with a button and success feedback.
from moutils import CopyToClipboard
c = CopyToClipboard(text="hello world")Run terminal commands in notebooks with real-time output streaming.
from moutils import shell
shell("ls -la")
shell("npm install", working_directory="./frontend")Detect the user's preferred color scheme (light or dark). Automatically updates when the preference changes.
from moutils import ColorScheme
cs = ColorScheme()
cs.scheme # "light" or "dark"
cs.prefers_dark # True or FalseDetect the browser window dimensions. Updates on resize (debounced).
from moutils import ViewportSize
vs = ViewportSize()
vs.width # e.g. 1920
vs.height # e.g. 1080Detect whether the browser has network connectivity.
from moutils import OnlineStatus
os_ = OnlineStatus()
os_.online # True or FalseDetect whether the browser tab is currently active or hidden.
from moutils import PageVisibility
pv = PageVisibility()
pv.visible # True or False
pv.state # "visible" or "hidden"Get the user's geographic coordinates. Opt-in — set enabled=True to request permission.
from moutils import Geolocation
geo = Geolocation(enabled=True)
geo.latitude # e.g. 37.7749
geo.longitude # e.g. -122.4194
geo.accuracy # meters
geo.error # error message, if anyCapture a still image from the webcam. Opt-in — set enabled=True to request camera access.
from moutils import CameraCapture
cam = CameraCapture(enabled=True, width=640, height=480)
cam.image_data # base64 data URL of the captured imageSend browser notifications. Automatically requests permission when needed.
from moutils import Notification
n = Notification(title="Done!", body="Your computation finished.")
n.send = True # fires the notification
n.permission # "default", "granted", or "denied"Listen for global keyboard shortcuts with modifier key support.
from moutils import KeyboardShortcut
ks = KeyboardShortcut(shortcut="ctrl+k")
ks.pressed # True when the shortcut is pressed
ks.event # dict with key event detailsEquivalent to list(map(fn, *iterables)) driven by ThreadPoolExecutor,
ProcessPoolExecutor, or InterpreterPoolExecutor (python >= 3.14) from
concurrent.futures, respectively, with a Marimo progress bar or spinner.
A spinner is used if the length cannot be automatically determined.
Inspired by https://tqdm.github.io/docs/contrib.concurrent/.
from moutils.concurrent import thread_map, process_map, interpreter_map
def add_one(x):
return x + 1
results: list[int] = thread_map(add_one, range(1000))
# Can specify title, max_workers, etc.
results = process_map(add_one, range(1000), title="Process map", max_workers=2)
results = interpreter_map(add_one, range(1000)) # Only available for Python >=3.14Button that opens the browser print dialog when clicked.
from moutils import PrintPageButton
btn = PrintPageButton()Programmatically trigger the browser print dialog.
import moutils
moutils.print_page()Button that captures a DOM element as a PNG and downloads it.
from moutils import ScreenshotButton
btn = ScreenshotButton(locator="#my-chart", filename="chart.png")Programmatically screenshot a DOM element and download as PNG.
import moutils
moutils.screenshot(locator="#my-chart", filename="chart.png")We use uv for development.
Specific notebook
uv run marimo edit notebooks/example.pyWorkspace
uv run --active marimo edit --port 2718uv tool install pre-commit
pre-commitTo run all tests:
pytest -v tests/