htmlGUI

htmlGUI is a lightweight, immediate-mode GUI toolkit for browser overlays inspired by imGUI.
It is designed for tools, debug panels, in-page controls, and browser extension UIs.

---

✨ Highlights

• Immediate-mode API (ImGui.frame(() => { ... })) with simple state models.
• Draggable and resizable windows with close support.
• Shadow DOM isolation to reduce style conflicts with host pages.
• Change-driven rendering (ImGui.invalidate()) instead of mandatory full-time loops.
• Built-in widgets for forms, menus, plots, tabs, trees, and more.
• Theme system with presets (dark, light, contrast) and CSS variable overrides.
• Browser extension friendly (MV3 demo included).

---

📦 What is included

• Runtime source: src/index.js
• Prebuilt bundles: dist/imgui-web.esm.js, dist/imgui-web.iife.js
• Type definitions: types/index.d.ts
• Extension demo: examples/extension/*
• Docs: docs/api-reference.md, docs/extension-getting-started.md

---

🚀 Quick start (ESM)

Use the ESM bundle in a browser environment:

import ImGui from "./dist/imgui-web.esm.js";

const state = {
  open: { value: true },
  enabled: { value: true },
  speed: { value: 50 },
  theme: { value: "dark" }
};

ImGui.mount({ shadow: "open", theme: "dark" });

ImGui.frame(() => {
  ImGui.begin("Demo", { x: 48, y: 48, width: 360, height: 240, open: state.open }, () => {
    ImGui.checkbox("Enabled", state.enabled);
    ImGui.sliderInt("Speed", state.speed, 0, 100);
    ImGui.combo("Theme", state.theme, ["dark", "light", "contrast"]);
    ImGui.theme.set(state.theme.value);
  });
});

---

🧩 Browser extension usage (MV3)

The repository includes a ready example in examples/extension.

1. Copy the extension files from examples/extension into your unpacked extension folder.
2. Load the folder in Chrome via Extensions → Developer mode → Load unpacked.
3. Open any page to see the overlay.

Minimal MV3 manifest:

{
  "manifest_version": 3,
  "name": "ImGui Web Injection Demo",
  "version": "0.1.0",
  "permissions": ["scripting", "activeTab", "tabs"],
  "host_permissions": ["<all_urls>"],
  "action": {
    "default_title": "ImGui Web Demo Controls",
    "default_popup": "popup.html"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["imgui-web.iife.js", "content.js"],
      "run_at": "document_idle"
    }
  ],
  "web_accessible_resources": [
    {
      "resources": ["imgui-web.esm.js"],
      "matches": ["<all_urls>"]
    }
  ]
}

---

🧠 Core concepts

1) Mount once

ImGui.mount() creates the host root for windows.

2) Render through a frame callback

ImGui.frame(fn) registers your UI function.

3) Keep mutable models

Most controls use { value: ... } models so state persists across re-renders.

4) Re-render on demand

Call ImGui.invalidate() when your code changes state outside direct control events.

---

🎨 Theming

Use preset themes:

ImGui.theme.set("dark");
ImGui.theme.set("light");
ImGui.theme.set("contrast");

Or override CSS variables:

ImGui.theme.set("dark", {
  "--imgui-accent": "#7c5cff",
  "--imgui-radius": "4px"
});

---

🧰 Widget coverage

Category	APIs
Lifecycle	mount, frame, invalidate, begin, end
Layout	text, separator, sameLine, columns, spacing, indent
Inputs	button, checkbox, radio, inputText, sliderFloat, sliderInt, dragFloat, dragInt, combo, colorPicker
Menus & hints	menuBar, contextMenu, tooltip, link
Structure	collapsingHeader, treeNode, beginTabs, tabItem
Data display	progressBar, plotLines, plotHistogram
Extensibility	use, registerWidget, theme.set

For full signatures and option details, see API Reference.

---

🗂️ Project layout

htmGUI/
├─ dist/
│  ├─ imgui-web.esm.js
│  └─ imgui-web.iife.js
├─ docs/
│  ├─ api-reference.md
│  └─ extension-getting-started.md
├─ examples/
│  └─ extension/
│     ├─ content.js
│     ├─ imgui-web.esm.js
│     ├─ imgui-web.iife.js
│     ├─ manifest.json
│     ├─ popup.css
│     ├─ popup.html
│     └─ popup.js
├─ src/
│  └─ index.js
├─ types/
│  └─ index.d.ts
└─ imgui-web.js

---

📚 Documentation

• API reference
• Browser extension getting started