A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
/* Copyright 2026 Marimo. All rights reserved. */
import { Provider } from "jotai";
import { isValidElement, type JSX } from "react";
import ReactDOM, { type Root } from "react-dom/client";
import { ErrorBoundary } from "@/components/editor/boundary/ErrorBoundary";
import { TooltipProvider } from "@/components/ui/tooltip";
import { cellIdsAtom, notebookAtom } from "@/core/cells/cells";
import { OBJECT_ID_ATTR } from "@/core/dom/ui-element-constants";
import { UI_ELEMENT_REGISTRY } from "@/core/dom/uiregistry";
import { LocaleProvider } from "@/core/i18n/locale-provider";
import { renderHTML } from "@/plugins/core/RenderHTML";
import { invariant } from "@/utils/invariant";
import type { CellId, UIElementId } from "../../cells/ids";
import { store } from "../../state/jotai";
import {
ISLAND_CSS_CLASSES,
ISLAND_DATA_ATTRIBUTES,
ISLAND_SOURCE_CHANGED_EVENT,
ISLAND_TAG_NAMES,
} from "../constants";
import { extractIslandCodeFromEmbed, retainIslandSource } from "../parse";
import { MarimoOutputWrapper } from "./output-wrapper";
/**
* Configuration for rendering a marimo island
*/
export interface IslandRenderConfig {
html: string;
codeCallback: () => string;
editor: JSX.Element | null;
}
/**
* A custom element that renders the output of a marimo cell.
*
* This web component wraps marimo cell outputs and provides interactive
* functionality like re-running cells and copying code.
*/
export class MarimoIslandElement extends HTMLElement {
private connectionGeneration = 0;
private root?: Root;
private renderConfig?: IslandRenderConfig;
private runtimeAppId?: string;
private runtimeCellId?: CellId;
private unsubscribeCellIds?: () => void;
public static readonly tagName = ISLAND_TAG_NAMES.ISLAND;
public static readonly outputTagName = ISLAND_TAG_NAMES.CELL_OUTPUT;
public static readonly codeTagName = ISLAND_TAG_NAMES.CELL_CODE;
public static readonly editorTagName = ISLAND_TAG_NAMES.CODE_EDITOR;
public static readonly styleNamespace = ISLAND_CSS_CLASSES.NAMESPACE;
public constructor() {
super();
this.classList.add(MarimoIslandElement.styleNamespace);
}
/**
* Gets the app ID from the element's data attribute
*/
public get appId(): string {
const appId = this.getAttribute(ISLAND_DATA_ATTRIBUTES.APP_ID);
invariant(appId, "Missing data-app-id attribute");
return appId;
}
/**
* Whether this island is reactive (has code sent to Python for execution)
*/
public get isReactive(): boolean {
return this.getAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE) === "true";
}
/**
* Gets the cell ID by looking up the cell index in the notebook state.
* Returns undefined for non-reactive islands (they have no corresponding cell).
*/
public get cellId(): CellId | undefined {
if (!this.isReactive) {
return undefined;
}
const cellId = this.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID);
if (cellId) {
return cellId as CellId;
}
const cellIdx = this.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX);
if (!cellIdx) {
return undefined;
}
return this.getCellIdFromIndex(Number.parseInt(cellIdx, 10));
}
/**
* Gets the code for this island cell
*/
public get code(): string {
return extractIslandCodeFromEmbed(this);
}
/**
* Looks up a cell ID from the notebook state by index
*/
private getCellIdFromIndex(idx: number): CellId | undefined {
const { cellIds } = store.get(notebookAtom);
return cellIds.at(idx);
}
/**
* Called when the element is added to the DOM.
*
* Deferred to a microtask because `defineCustomElement` during
* `kernel-ready` upgrades all existing elements synchronously,
* which can happen inside a React render cycle. Rendering
* synchronously from there causes "unmount during render" warnings.
*/
public connectedCallback(): void {
const connectionGeneration = ++this.connectionGeneration;
this.addEventListener(
ISLAND_SOURCE_CHANGED_EVENT,
this.handleSourceChanged,
);
// Capture config synchronously (before children get cleared by createRoot).
// A reconnected element reuses the source captured on its first mount.
if (this.querySelector(MarimoIslandElement.outputTagName)) {
this.renderConfig = this.extractRenderConfig();
}
invariant(this.renderConfig, "Missing island render source");
this.runtimeAppId = this.appId;
this.runtimeCellId = this.hasAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)
? this.cellId
: undefined;
this.syncCellIdsSubscription();
queueMicrotask(() => {
// Guard against disconnect between connectedCallback and microtask
if (
!this.isConnected ||
connectionGeneration !== this.connectionGeneration
) {
return;
}
this.root = ReactDOM.createRoot(this);
this.renderIsland();
});
}
private handleSourceChanged = (): void => {
if (this.querySelector(MarimoIslandElement.outputTagName)) {
this.renderConfig = this.extractRenderConfig();
this.querySelector(MarimoIslandElement.outputTagName)?.remove();
this.querySelector(MarimoIslandElement.codeTagName)?.remove();
}
this.runtimeCellId =
this.isReactive && this.runtimeAppId === this.appId
? this.cellId
: undefined;
this.runtimeAppId = this.appId;
this.syncCellIdsSubscription();
this.renderIsland();
};
private syncCellIdsSubscription(): void {
if (this.isReactive) {
this.unsubscribeCellIds ??= store.sub(cellIdsAtom, () => {
this.runtimeCellId = this.cellId;
this.renderIsland();
});
return;
}
this.unsubscribeCellIds?.();
this.unsubscribeCellIds = undefined;
}
/**
* Extracts configuration needed for rendering
*/
private extractRenderConfig(): IslandRenderConfig {
const output = this.querySelectorOrThrow(MarimoIslandElement.outputTagName);
const initialOutput = output.innerHTML;
const optionalEditor = this.getOptionalEditor();
const code = this.code;
retainIslandSource(this, { code, output: initialOutput });
// Read objectId directly from the DOM before createRoot clears children.
// optionalEditor is a <RenderHTML> wrapper, so its .props don't carry the
// underlying element's attributes — we must grab objectId here instead.
const editorElement = this.querySelector(MarimoIslandElement.editorTagName);
const editorObjectId = (
editorElement?.parentElement as Element | null
)?.getAttribute(OBJECT_ID_ATTR) as UIElementId | null;
const codeCallback: () => string =
optionalEditor && editorObjectId
? () => {
const val = UI_ELEMENT_REGISTRY.lookupValue(editorObjectId);
return val !== undefined ? String(val) : code;
}
: () => code;
return {
html: initialOutput,
codeCallback,
editor: optionalEditor,
};
}
/**
* Renders the island with React
*/
private renderIsland(): void {
const config = this.renderConfig;
if (!config) {
return;
}
const { html, codeCallback, editor } = config;
const cellId = this.runtimeCellId;
const alwaysShowRun = !!editor;
const trimmedHtml = html.trim();
const isEmpty = trimmedHtml === "<span></span>" || trimmedHtml === "";
const initialHtml = isEmpty ? null : renderHTML({ html: trimmedHtml });
// Non-reactive islands have no cell in the kernel — just render static HTML
if (!cellId) {
this.removeAttribute("data-status");
this.root?.render(
<ErrorBoundary>
<Provider store={store}>
<LocaleProvider>{initialHtml}</LocaleProvider>
</Provider>
</ErrorBoundary>,
);
return;
}
this.root?.render(
<ErrorBoundary>
<Provider store={store}>
<LocaleProvider>
<TooltipProvider>
<MarimoOutputWrapper
cellId={cellId}
codeCallback={codeCallback}
alwaysShowRun={alwaysShowRun}
>
{initialHtml}
</MarimoOutputWrapper>
{editor}
</TooltipProvider>
</LocaleProvider>
</Provider>
</ErrorBoundary>,
);
}
/**
* Attempts to find and render an optional code editor.
*
* The DOM structure is:
* <marimo-cell-output>
* <div data-marimo-element> ← parent wrapper from Python render
* <marimo-code-editor .../>
* </div>
* </marimo-cell-output>
*
* We take the parent's outerHTML (the wrapper div) so that the rendered
* React element includes the UI element registration attributes.
*
* @returns A React element for the editor, or null if not found
*/
private getOptionalEditor(): JSX.Element | null {
const optionalElement = this.querySelector(
MarimoIslandElement.editorTagName,
);
const html = (optionalElement?.parentNode as Element)?.outerHTML;
if (html) {
// Convert HTML to virtual DOM
const virtualDom = renderHTML({ html });
// Verify it's a valid React element
if (isValidElement(virtualDom)) {
return virtualDom;
}
}
return null;
}
/**
* Queries for an element and throws if not found
*/
private querySelectorOrThrow(selector: string): Element {
const element = this.querySelector(selector);
invariant(element, `Missing ${selector} element`);
return element;
}
/**
* Cleanup when element is removed from DOM
*/
public disconnectedCallback(): void {
this.removeEventListener(
ISLAND_SOURCE_CHANGED_EVENT,
this.handleSourceChanged,
);
this.unsubscribeCellIds?.();
this.unsubscribeCellIds = undefined;
const root = this.root;
this.root = undefined;
// Defer unmount to avoid "unmount during render" race
if (root) {
queueMicrotask(() => root.unmount());
}
}
}