Streamlit JavaScript Evaluator Component

1.0.0 · active · verified Thu Apr 16

streamlit-js-eval is a custom Streamlit component that enables developers to execute arbitrary JavaScript expressions directly within a Streamlit application. It facilitates interactions with the browser DOM, local storage, window properties, and more, returning results back to Python. The current version is 1.0.0, and it follows an infrequent release cadence, with stability being a primary focus.

Common errors

```
ImportError: cannot import name 'streamlit_js_eval' from 'streamlit_js_eval'
```
cause The `streamlit-js-eval` package is either not installed, or there's a typo in the import statement.

fix Ensure the library is installed by running `pip install streamlit-js-eval`. Verify your import statement is `from streamlit_js_eval import streamlit_js_eval`.
```
JavaScript expression results in None or doesn't update as expected.
```
cause The component might not have executed the JavaScript, or Streamlit did not capture its return value, often due to a missing/duplicate `key`, or `want_result` being `False`.

fix Ensure each `streamlit_js_eval` call has a unique `key`. If you expect a result, make sure `want_result` is not set to `False`. For fire-and-forget operations, setting `want_result=False` is efficient. If you need re-evaluation on every run, consider using a dynamic `key` or updating `js_expressions` to force a change.
```
streamlit.errors.StreamlitAPIException: Every Streamlit component must have a unique key. If you are seeing this error, it means that you have streamlit_js_eval defined multiple times with the same key.
```
cause Multiple `streamlit_js_eval` calls in the same Streamlit app instance share the same `key` value, which is not allowed by Streamlit's component API.

fix Assign a unique `key` string to every instance of `streamlit_js_eval` in your application (e.g., `key='eval_id_1'`, `key='eval_id_2'`).

Warnings

gotcha JavaScript expressions are evaluated client-side on each Streamlit rerun. Results are cached and only updated if the `js_expressions` or `key` changes, or if `streamlit_js_eval` is explicitly rerun. Be mindful of when and how results are updated in a reactive Streamlit application.
Fix: Ensure a unique `key` is used for each distinct evaluation call. If results aren't updating as expected, consider triggering a Streamlit rerun or ensuring the JS expression itself produces a new value. For fire-and-forget actions that don't require a return value, set `want_result=False`.
gotcha Evaluating arbitrary JavaScript from user input or untrusted sources can lead to Cross-Site Scripting (XSS) vulnerabilities. Treat all `js_expressions` inputs as potentially malicious.
Fix: Sanitize or strictly validate any `js_expressions` derived from user input. Limit the scope of executable JavaScript to only what is absolutely necessary and safe.
gotcha Like all Streamlit components, `streamlit_js_eval` requires a unique `key` parameter for each instance to maintain state across reruns. Failing to provide a unique key can lead to unexpected behavior or `StreamlitAPIException` errors.
Fix: Always provide a unique `key` string (e.g., `key="my_unique_eval_1"`) to every `streamlit_js_eval` call in your application.

Install

pip install streamlit-js-eval Install `streamlit-js-eval`

Imports

streamlit_js_eval

from streamlit_js_eval import streamlit_js_eval

Quickstart

This quickstart demonstrates how to use `streamlit_js_eval` to interact with browser-side JavaScript, including retrieving the current URL, setting and getting local storage values, getting screen dimensions, and performing a page redirect. Each `streamlit_js_eval` call requires a unique `key`.

import streamlit as st
from streamlit_js_eval import streamlit_js_eval

st.set_page_config(layout="wide")
st.title("Streamlit JS Eval Demo")

st.header("1. Get Browser URL")
current_url = streamlit_js_eval(js_expressions="window.location.href", key="get_url")
st.write(f"**Current URL:** `{current_url}`")

st.header("2. Set Local Storage Value")
if st.button("Set 'myKey' to 'myValue' in Local Storage"):
    streamlit_js_eval(js_expressions="localStorage.setItem('myKey', 'myValue');", key="set_ls_value", want_result=False)
    st.success("Value set! Refresh the page to see it in browser dev tools.")

st.header("3. Get Local Storage Value")
local_storage_val = streamlit_js_eval(js_expressions="localStorage.getItem('myKey');", key="get_ls_value")
st.write(f"**Local Storage 'myKey':** `{local_storage_val}`")

st.header("4. Get Screen Width")
screen_width = streamlit_js_eval(js_expressions="screen.width", key="get_screen_width")
st.write(f"**Screen Width:** `{screen_width}px`")

st.header("5. Redirect Page (example)")
if st.button("Go to Streamlit.io"):
    streamlit_js_eval(js_expressions="window.location.href='https://streamlit.io';", key="redirect_streamlit", want_result=False)

view raw JSON →