Skip to Content
OrbixDocs
Block SDK · Guides

HTML and polyglot blocks

Author zero-build HTML blocks using <orbix-*> custom elements, data-orbix-* bindings, and the window.Orbix JavaScript runtime.

In addition to TypeScript/React blocks built with defineBlock, Block Studio supports standalone .html files (as well as .svelte, .vue, .py, and .sql blocks) that execute inside the cross-site rb-<hash>.orbixblocks.com sandbox.

Every HTML block automatically receives --orbix-* theme CSS variables, automatic iframe height reporting via ResizeObserver, and the OrbixHtmlRuntime bridge. You can wire an HTML block at three levels depending on how much JavaScript you want to write.

1. Autonomous <orbix-*> custom elements

Drop <orbix-*> tags directly into HTML markup to render live document metadata, database views, polls, or port bindings with no <script> tag:

Custom elementPurpose
<orbix-doc-title>Displays the active document title and updates on rename.
<orbix-doc-stats>Renders word count, block count, and estimated reading time.
<orbix-doc-outline>Clickable heading outline that scrolls the host page on click.
<orbix-doc-blocks> / <orbix-append-block>Lists document blocks or renders a button/form that appends blocks.
<orbix-db-table> / <orbix-db-metric> / <orbix-db-form>Displays rows, aggregate metrics (<orbix-stat>), or an insert form for a workspace database.
<orbix-workspace-pages> / <orbix-knowledge-graph>Lists scoped workspace pages or renders the page link graph (<orbix-graph>).
<orbix-state> / <orbix-personal-note> / <orbix-team-poll>Declarative shared state display, private viewer scratchpad, or multi-member poll.
<orbix-port-in> / <orbix-port-out>Reads an incoming block graph port or publishes an output port value.
<orbix-ai-box>Prompt form (<orbix-ai-prompt>) that generates text via the host AI service and can append results to the page.

2. Declarative data-orbix-* bindings and actions

Bind <input>, <textarea>, <select>, or text elements to block state without writing event listeners:

  • data-orbix-bind="key" — two-way binding to shared block state (add data-orbix-scope="personal" for per-viewer state and data-orbix-default="..." for an initial value).
  • data-orbix-bind-personal="key" / data-orbix-bind-team="key" — explicit personal or team state bindings.
  • data-orbix-action — click triggers on <button> elements:
    • data-orbix-action="state-inc" / "state-dec" (data-orbix-key="count", data-orbix-step="1")
    • data-orbix-action="state-set" (data-orbix-key="status", data-orbix-value="done")
    • data-orbix-action="append-block" (data-orbix-block-type="callout", data-orbix-content="...")
    • data-orbix-action="navigate" (data-orbix-page="Roadmap")
    • data-orbix-action="toast" (data-orbix-message="Saved", data-orbix-toast-type="success")

3. Imperative window.Orbix JavaScript API

For custom logic, charts, or calculations, read and write through window.Orbix (also aliased as window.orbix):

roi-calculator.html
<div class="card">
  <div class="header">
    <strong>Estimate for <orbix-doc-title></orbix-doc-title></strong>
  </div>

  <label>
    Engineers
    <input type="number" data-orbix-bind="teamSize" data-orbix-default="8" min="1" />
  </label>

  <label>
    Hours saved / week
    <input type="number" data-orbix-bind="hoursSaved" data-orbix-default="4" min="0" />
  </label>

  <p id="summary"></p>
  <button id="insert-btn" type="button">Insert callout into page</button>
</div>

<style>
  .card {
    padding: 14px;
    border-radius: 12px;
    background: var(--orbix-card-bg, #111216);
    border: 1px solid var(--orbix-surface-border, rgba(255, 255, 255, 0.08));
    color: var(--orbix-text-primary, #f3f4f6);
    font-family: var(--orbix-font, system-ui, sans-serif);
    display: grid;
    gap: 10px;
  }
  label {
    display: flex;
    justify-content: space-between;
    align-items: center;
    font-size: 13px;
  }
</style>

<script>
  const summaryEl = document.getElementById('summary');
  const insertBtn = document.getElementById('insert-btn');

  function recompute() {
    const team = Number(Orbix.state.get('teamSize', 8)) || 8;
    const hours = Number(Orbix.state.get('hoursSaved', 4)) || 4;
    const annual = team * hours * 52;
    summaryEl.textContent = annual.toLocaleString() + ' hours / year';
    Orbix.ports.setOutput('annualHoursSaved', annual, 'Annual Hours Saved');
  }

  Orbix.state.onChange(recompute);
  recompute();

  insertBtn.addEventListener('click', () => {
    Orbix.doc.appendBlock('callout', 'Projected savings: ' + summaryEl.textContent);
    Orbix.ui.toast('Appended summary callout', 'success');
  });
</script>

window.Orbix namespaces

  • Orbix.state — get(key, fallback?, { scope? }), set(keyOrObj, value?, { scope? }), getAll(), personal, team, member, onChange(cb)
  • Orbix.doc — getDocument(), headings, wordCount, blockCount, getBlock(id), findBlocksByType(type), appendBlock(type, content, props?), insertBlock(...), updateBlock(...), deleteBlock(id), scrollToHeading(idOrText), onChange(cb)
  • Orbix.workspace — getPages(), getGraph('workspace' | 'local'), search(query), navigateToPage(idOrTitle), createPage(title, parentId?), onChange(cb)
  • Orbix.db — list(), query(nameOrId, filter?), rows(nameOrId, filter?), insert(nameOrId, values), update(nameOrId, recordId, patch), delete(nameOrId, recordId), onChange(cb)
  • Orbix.ports — getInput(port, fallback?), setOutput(port, value, label?), onInput(port, cb)
  • Orbix.ai — await Orbix.ai.generate(prompt, includeDocContext?)
  • Orbix.user & Orbix.theme — Orbix.user.current, Orbix.user.collaborators, Orbix.theme.isLight, Orbix.theme.tokens, Orbix.theme.onChange(cb)
  • Orbix.ui — toast(message, type?), reportHeight()

Workspace read air-gap inside HTML frames

Once an HTML block reads document, workspace, or database content (Orbix.doc.getDocument(), Orbix.workspace.getPages(), Orbix.db.query(), or <orbix-doc-*> / <orbix-db-*> tags), the runtime engages a workspace-read air-gap so document contents cannot be exfiltrated to arbitrary external origins without explicit host authorization.

On this page