PondPilot Widget API Reference

Quick Start

<!-- Add widget class to any <pre> tag -->
<pre class="pondpilot-snippet">
SELECT * FROM users;
</pre>

<!-- Load the widget -->
<script src="https://unpkg.com/pondpilot-widget@latest"></script>

Global Configuration

`window.PONDPILOT_BASE_URL`

Set the base URL for your PondPilot instance before loading the widget:

<script>
  window.PONDPILOT_BASE_URL = "https://app.pondpilot.io";
</script>
<script src="path/to/pondpilot-widget.js"></script>

`window.PONDPILOT_CONFIG`

Provide multiple defaults in a single object before loading the script:

<script>
  window.PONDPILOT_CONFIG = {
    autoInit: false,
    initQueries: ["INSTALL httpfs;", "LOAD httpfs;"],
    resetQueries: ["DROP TABLE IF EXISTS scratch_table;"]
  };
</script>
<script src="path/to/pondpilot-widget.js"></script>

`window.PONDPILOT_INIT_QUERIES`

Legacy helper for setting init queries via a global:

<script>
  window.PONDPILOT_INIT_QUERIES = ["INSTALL spatial;", "LOAD spatial;"];
</script>

`window.PONDPILOT_RESET_QUERIES`

Run cleanup SQL whenever a widget resets:

<script>
  window.PONDPILOT_RESET_QUERIES = ["DROP TABLE IF EXISTS scratch_table;"];
</script>

JavaScript API

All helpers live under window.PondPilot.

`PondPilot.config(partial)`

Merge configuration values. Returns the updated snapshot.

PondPilot.config({
  selector: "pre.sql-demo",
  baseUrl: "https://cdn.example.com/data",
  autoInit: false,
  initQueries: ["INSTALL httpfs", "LOAD httpfs"],
  resetQueries: ["DROP TABLE IF EXISTS scratch_table;"],
});

`PondPilot.getConfig()`

Inspect the current configuration.

console.log(PondPilot.getConfig());

`PondPilot.init(target?, options?)`

Initialize widgets. Accepts:

nothing (use config.selector)
CSS selector string
single HTMLElement
NodeList/array of elements

PondPilot.init(); // default selector
PondPilot.init("pre.sql-demo", { theme: "dark" });

`PondPilot.create(element, options?)`

Transform one element immediately. Returns the widget instance (or null).

const pre = document.querySelector(".pondpilot-snippet");
const widget = PondPilot.create(pre, { editable: false });

`PondPilot.destroy(target?)`

Remove widgets and release resources. Pass a selector/element to limit scope.

PondPilot.destroy(); // everything
PondPilot.destroy(".sidebar .pondpilot-widget");

`PondPilot.registerTheme(name, definition)`

PondPilot.registerTheme("forest", {
  extends: "dark",
  config: {
    bgColor: "#102418",
    textColor: "#dcfce7",
    borderColor: "#14532d",
    editorBg: "#06270f",
    editorText: "#f0fdf4",
    editorFocusBg: "#0d4020",
    controlsBg: "rgba(12, 48, 25, 0.72)",
    primaryBg: "#22c55e",
    primaryText: "#052e16",
    primaryHover: "#16a34a",
    secondaryBg: "rgba(34, 197, 94, 0.2)",
    secondaryText: "#bbf7d0",
    secondaryHover: "rgba(34, 197, 94, 0.32)",
    mutedText: "#86efac",
    errorText: "#f87171",
    errorBg: "rgba(248, 113, 113, 0.12)",
    errorBorder: "rgba(248, 113, 113, 0.32)",
    tableHeaderBg: "rgba(34, 197, 94, 0.16)",
    tableHeaderText: "#bbf7d0",
    tableHover: "rgba(34, 197, 94, 0.12)",
    syntaxKeyword: "#4ade80",
    syntaxString: "#fbbf24",
    syntaxNumber: "#60a5fa",
    syntaxComment: "#86efac",
    syntaxSpecial: "#f97316",
    syntaxIdentifier: "#facc15",
    fontFamily: "Inter, system-ui, sans-serif",
    editorFontFamily: "'JetBrains Mono', monospace",
    fontSize: "14px",
    editorFontSize: "13px",
    buttonFontSize: "13px",
    metadataFontSize: "12px",
  },
});