Push-Based Widget Module Pattern

Use this pattern when a UI sidebar or widget component needs to be updated by its caller (push-based) rather than fetching data itself. Instead of a class or framework component, implement the widget as a plain module with singleton state, a factory function to create the DOM, and an update function to efficiently patch it.

When to Use

• A sidebar, panel, or widget is rendered once but updated frequently with new data.
• The data source lives outside the component (e.g., a parent controller, event bus, or store).
• You want lightweight partial re-renders without rebuilding the entire DOM tree.
• You prefer a simple module interface over a class-based or framework-based component.

Core Structure

widgets/
  MyWidget.ts          # The module (singleton state + exports)
  MyWidget.types.ts    # (Optional) Exported data interface

Step-by-Step Instructions

1. Define the Data Interface

Export a typed interface so callers know exactly what data to push.

// MyWidget.types.ts  (or inline at top of MyWidget.ts)
export interface MyWidgetData {
  title: string;
  items: string[];
  status: "idle" | "active" | "error";
  // ... all fields the widget needs to render
}

2. Declare Module-Level Singleton Refs

At module scope, keep references to the container and any frequently updated child nodes. This avoids querying the DOM on every update.

// MyWidget.ts
import type { MyWidgetData } from "./MyWidget.types";

// Singleton DOM refs
let containerEl: HTMLElement | null = null;
let titleEl: HTMLElement | null = null;
let itemListEl: HTMLElement | null = null;
let statusEl: HTMLElement | null = null;

// Current state snapshot (optional — useful for diffing)
let currentData: MyWidgetData | null = null;

3. Export a Factory Function (

createMyWidget

)

The factory builds the full DOM tree once, stores refs to mutable nodes, and returns the root element to be mounted by the caller.

export function createMyWidget(): HTMLElement {
  // Build the container
  containerEl = document.createElement("aside");
  containerEl.className = "my-widget";

  // Build static structure; keep refs to dynamic parts
  titleEl = document.createElement("h2");
  titleEl.className = "my-widget__title";

  itemListEl = document.createElement("ul");
  itemListEl.className = "my-widget__list";

  statusEl = document.createElement("span");
  statusEl.className = "my-widget__status";

  // Compose the tree
  const header = document.createElement("header");
  header.appendChild(titleEl);
  header.appendChild(statusEl);

  containerEl.appendChild(header);
  containerEl.appendChild(itemListEl);

  return containerEl;
}

Rule:

createMyWidget

should be callable only once per page. If called again, consider returning the existing

containerEl

(idempotent factory).

4. Export an Update Function (

updateMyWidget

)

The update function receives the new data object and performs surgical DOM mutations on the stored refs. It does NOT rebuild the whole tree.

export function updateMyWidget(data: MyWidgetData): void {
  if (!containerEl) {
    console.warn("updateMyWidget called before createMyWidget");
    return;
  }

  currentData = data;

  // Update only what changed
  if (titleEl) titleEl.textContent = data.title;
  if (statusEl) {
    statusEl.textContent = data.status;
    statusEl.dataset.status = data.status; // for CSS hooks
  }

  // Rebuild only dynamic list items
  if (itemListEl) {
    itemListEl.innerHTML = ""; // clear previous items
    data.items.forEach((item) => {
      const li = document.createElement("li");
      li.textContent = item;
      itemListEl!.appendChild(li);
    });
  }
}

Optimization tip: For large lists, compare

currentData

to

data

before clearing and rebuilding, or use a keyed reconciliation approach.

5. Caller Usage Pattern

The caller mounts the widget once and pushes updates whenever its data changes.

import { createMyWidget, updateMyWidget } from "./widgets/MyWidget";
import type { MyWidgetData } from "./widgets/MyWidget.types";

// Mount once
const sidebar = document.getElementById("sidebar")!;
sidebar.appendChild(createMyWidget());

// Push updates (e.g., from a store subscription, WebSocket, timer)
function onDataChange(newData: MyWidgetData) {
  updateMyWidget(newData);
}

// Example: push an initial state immediately
onDataChange({
  title: "Today's Focus",
  items: ["Task A", "Task B"],
  status: "active",
});

Full Module Template

// widgets/MyWidget.ts

export interface MyWidgetData {
  // Define all fields here
}

// --- Singleton state ---
let containerEl: HTMLElement | null = null;
// Add more refs as needed per section of the widget

// --- Factory ---
export function createMyWidget(): HTMLElement {
  if (containerEl) return containerEl; // idempotent

  containerEl = document.createElement("aside");
  // ... build DOM, store refs ...
  return containerEl;
}

// --- Update ---
export function updateMyWidget(data: MyWidgetData): void {
  if (!containerEl) return;
  // ... patch DOM refs with new data ...
}

Guidelines & Best Practices

containerEl

querySelector

data-*

destroyMyWidget()

Anti-Patterns to Avoid

• ❌ Class with constructor — adds instantiation overhead and prevents the clean factory/update split.
• ❌ Querying the DOM in the update function (

  document.querySelector(...)

  ) — slow and fragile.
• ❌ Rebuilding the entire tree on every update — defeats the purpose of the module-level refs.
• ❌ Mixing data-fetching into the widget module — breaks the push-based contract.