← All posts

API & helpers

window.JZ: helpers to drive buttons, sliders and Output Console from code

15 May 2026 · by JustZix Team

For a moment, forget that JustZix injects CSS and JS into every page. Focus on the fact that every action — button, slider, select, toggle3, input, textarea — is a live DOM element you can drive from other code. You need two separate namespaces in MAIN world: window.JZ (action helpers) and window.JUSTZIX (logger). Each has its own lifecycle, its own purpose, and they deliberately don't mix.

Why two namespaces and not one

Logger (write-only, dispatch to Output Console) and DOM addressability (read/manipulate elements that already live in the page DOM) are two different semantics. Packing them together would mix concerns. A user reading code sees JUSTZIX.log(...) and knows: "that's a logger". They see document.querySelector('[data-jz-action-id="x"]') and know: "that's a DOM query". Plus — native DOM API + data-* attributes always win over a proprietary wrapper (works with DevTools inspect, with third-party libraries, with copy-paste from the internet).

Idempotent — install is gated by version (_jzVersion for JZ, hook flag for JUSTZIX), so extension upgrades won't clobber namespaces mid-session.

Full API surface

// ============================================================
// window.JZ — Action helpers
// Operates on data-jz-action-id elements in DOM.
// May be taken by page scripts → fallback: native DOM query.
// ============================================================
JZ.action(labelOrId)     // Element by label OR id. Case-insensitive by label.
JZ.actionById(id)        // Element by data-jz-action-id. No label fallback.
JZ.actions()             // Array of all action elements in DOM.
JZ.labels()              // Array of labels (original case).
JZ.click(labelOrId)      // Programmatic click. For <select> picks first option.
                          // Returns true/false.
JZ.value(labelOrId)      // Current action value (string or null).
JZ.setValue(labelOrId, value)  // Programmatic setter + dispatches input + change.
JZ.bars()                // Array of all .jz-actions-bar in DOM.
JZ.barById(id)           // Bar by data-jz-bar-id.
JZ.floatingBtn()         // The JustZix floating button element (when enabled).

// ============================================================
// window.JUSTZIX — Logger (since v2.13.73, primary alias since v2.13.76)
// Dispatches to Output Console (kind='jz'); does NOT pipe to native console.*
// Brand name = vanishingly small collision risk. Works everywhere.
// ============================================================
JUSTZIX.log(...args)
JUSTZIX.warn(...args)
JUSTZIX.error(...args)
JUSTZIX.info(...args)
JUSTZIX.debug(...args)

// Aliases to the same API:
window.__JUSTZIX__       // always set (backwards-compat with v2.13.72-75)
window.JZ                // also, only when not taken — a shorter shortcut

// Fallback when window.JZ is taken by the page (e.g. Google Ads):
// → no JUSTZIX.click() equivalent; use native DOM.
document.querySelector('[data-jz-action-id="..."]').click();

Use case 1 — a button clicks another button

You have actions "Login → Dashboard → Stats". Three separate buttons in an action bar. Add a fourth "🚀 Quick" that runs all three in sequence:

// BUTTON action "Quick" — code field:
JZ.click('Login');
await new Promise(r => setTimeout(r, 800));
JZ.click('Dashboard');
await new Promise(r => setTimeout(r, 500));
JZ.click('Stats');
JUSTZIX.log('Quick flow done — 3 clicks in 1');

Bonus: this script knows nothing about the page, only about its own JustZix actions. Change the selectors inside "Login" / "Dashboard" — "Quick" keeps working, since it calls them by label.

Use case 2 — slider drives a CSS variable

SLIDER action "Brightness" (range 50-150, default 100). In its "Code" field:

// Slider runs this code on every change.
// `value` is an extraVar injected by the extension (since v2.12.2).
document.documentElement.style.setProperty('--brightness', value + '%');

Now in another action (BUTTON "Reset") you can programmatically set the slider's value:

JZ.setValue('Brightness', 100);  // Slider jumps to 100, CSS variable updated, brightness reset.
JUSTZIX.log('Brightness reset to 100%');

Same works for TOGGLE3 (3-state switches like "Dev / Staging / Prod"): JZ.setValue('Environment', 'staging') activates that specific state and runs its code.

Use case 3 — Output Console as a "scratch pad"

Output Console (since v2.13.66) is a pane that captures all console.log output from the page. Pages like Gmail spam the console with hundreds of lines per second. String filters help, but a better trick: write only your messages via JUSTZIX.log, then switch the pane to [J] (Just JustZix) mode.

// In a "Verify cart" action: log only YOUR messages, no page noise.
const items = document.querySelectorAll('.cart-item');
JUSTZIX.log(`Cart has ${items.length} items`);
items.forEach((it, i) => {
  const price = parseFloat(it.querySelector('.price')?.textContent || 0);
  JUSTZIX.log(`  [${i}] ${it.dataset.sku} — $${price}`);
});
const total = [...items].reduce((s, it) => s + parseFloat(it.querySelector('.price')?.textContent || 0), 0);
JUSTZIX.log(`Total: $${total}`);

The Output Console pane in [J] mode shows ONLY those 3 lines — completely clean, perfect for a QA toolbar or a client-facing context.

What if the page already has window.JZ?

The logger always works — JUSTZIX.log() has a brand name (vanishingly small collision risk) and is the primary. Plus window.__JUSTZIX__ is always set as a fallback alias. A window.JZ conflict affects only action helpers — and even then you have a native way out.

Some sites (e.g. Google Ads) have their own window.JZ. JustZix detects this: if window.JZ already exists when the logger installs, the extension does not overwrite the page's API and notes this in the Output Console welcome message. The short JZ shortcut is then reserved for the page — use JUSTZIX for logging and native DOM for actions:

// Logger: always JUSTZIX (works even when JZ is taken by the page)
JUSTZIX.log('Cart processed');

// Action click: when window.JZ is taken → use native DOM instead of JZ.click()
document.querySelector('[data-jz-action-id="actionId"]').click();
// Or by data-jz-key (label upper-case):
document.querySelector('.jz-actions-bar [data-jz-key="LOGIN"]').click();

That's deliberate design: data-jz-action-* + querySelector is a native pattern — it works with DevTools inspect, with third-party libraries, with copy-paste from the internet. JZ.click() is sugar — an optional indirection layer you can skip when it isn't available.

Pitfalls

• JZ.click() on INPUT/TEXTAREA only clicks them, doesn't change their value. To set text: JZ.setValue('Search', 'foo'). Other types (button, select, toggle3, slider) have a sensible click default.
• JZ.value()/setValue() got most complete since v2.13.33. Older versions lacked slider value on the dataset — if you see null for a slider, check your extension version.
• Label lookup is case-insensitive, but ID lookup is case-sensitive. Recommended: stick to labels (yours), not IDs (auto-generated).
• JUSTZIX.log does NOT pipe to DevTools console. Intentional — we want a separate channel for JustZix scripts. If you want DevTools — use regular console.log.
• JS Console only captures DevTools-style traffic, not JUSTZIX.log automatically. "console.log('hi')" in JS Console works as always; "JUSTZIX.log('hi')" in JS Console will NOT show up in Output Console unless you have an Output Console pane active in [J] or [C+J] mode.
• No JUSTZIX.click() or similar. Logger and action helpers are separate namespaces by design. When the page takes window.JZ, you trigger actions via native DOM (querySelector + data-jz-action-*) — that's the pattern, not a bug.

What's next

This closes the mini-series on JustZix windows on the frontend:

• CSS pane — live CSS editor in the tab
• JS Console — REPL with ↑↓ history
• JS pane — Run-on-demand
• window.JZ helpers (this post) — the programmatic API

All together this is a mini-IDE inside every browser tab, with a mini-API to drive your own buttons. Install JustZix and try it yourself — completely free, no account, no server.