WordPress Custom HTML Safety Checklist: Blocks, CSS, JS, QA

Interactive checklist

Check the block before you paste or publish

Complete this in a draft page, staging site, or copied block. A green-looking preview is not the same as a safe live block.

0 / 15 Draft review

1. Decide if Custom HTML is the right tool

Safe fit: a front-end calculator, checklist, quiz, prompt library, comparison table, or static embed you can fully test in a draft. Risky fit: anything that needs accounts, protected records, payments, private form storage, server secrets, or trusted backend validation. Use a plugin, theme template, form block, embed block, or backend when browser-only code cannot safely own the job.

2. Scope CSS so it cannot leak

Wrap the whole block in one unique ID such as #kingy-wp-html-safety-tool. Prefix selectors with that wrapper. Avoid styling body, main, .button, a, h2, input, or generic WordPress classes directly. Test near the site header, footer, forms, and reusable blocks so you catch accidental layout changes.

3. Keep JavaScript isolated

Use an immediately-invoked function or DOMContentLoaded handler instead of global function names. Attach listeners with querySelector inside the wrapper. Avoid inline onclick and document.write. Check that button IDs, selectors, and script order still work after WordPress saves the page.

4. Never expose secrets or protected actions

Do not paste API keys, passwords, tokens, application passwords, private URLs, or customer data into page HTML or JavaScript. Do not handle payments, logins, account changes, database writes, or private form submissions in a Custom HTML block alone. If the feature needs a secret, it needs server-side code or an approved provider integration.

5. Review embeds, forms, accessibility, and rollback

Prefer WordPress Embed or Form blocks when they do the job without custom code. Use semantic headings, labels, keyboard focus, readable contrast, and mobile tap targets. Back up the old block, test in draft/staging, and write the exact rollback step before publishing.

Safe vs risky patterns

Tiny examples that prevent big messes

<div id="kingy-example-tool">
  <button type="button" data-action="calculate">Calculate</button>
  <p data-result aria-live="polite"></p>
</div>
<style>
  #kingy-example-tool { max-width: 720px; }
  #kingy-example-tool button { min-height: 44px; }
</style>
<script>
(() => {
  const root = document.querySelector("#kingy-example-tool");
  if (!root) return;
  root.querySelector("[data-action]").addEventListener("click", () => {
    root.querySelector("[data-result]").textContent = "Result ready.";
  });
})();
</script>

<style>
  body, .button, input { font-size: 12px !important; }
</style>
<button onclick="calculate()">Pay now</button>
<script src="https://unknown.example/widget.js"></script>
<script>
  const API_KEY = "sk-live-private-key-do-not-paste";
  function calculate() {
    document.write(location.hash);
  }
</script>

Code smell helper

Paste a snippet and look for obvious risks

This is a quick helper, not a security scanner. It flags patterns that deserve human review before publishing.

Review notes

No snippet checked yet

Paste code to flag common issues like external scripts, inline handlers, likely secrets, unscoped CSS, forms, iframes, and global functions.

Codex prompt generator

Ask AI to build and review the block safely

Do not write code yet. I want to build a WordPress Custom HTML block for [audience] that does [job]. First decide whether Custom HTML is the right tool. Then plan the wrapper ID, HTML structure, scoped CSS, JavaScript behavior, accessibility, mobile layout, risks, rollback path, and test checklist.

Real risk vs security theater

Spend attention where it actually lowers risk

Real risk: exposed secrets

A private API key in page source is not private. Move the feature server-side.

Real risk: untrusted HTML

User-supplied HTML needs a sanitizer and context-aware output handling, not hope.

Theater: hiding complexity

Renaming a button or minifying a script does not make dangerous browser code safe.

Theater: “it works in preview”

Preview proves the happy path once. Safety needs save, live, logged-out, mobile, and rollback checks.

Glossary

Plain-English terms you will see in safety reviews

Scoped CSS: CSS that only applies inside one wrapper so it does not restyle the rest of WordPress.
Vanilla JavaScript: Browser JavaScript without React, jQuery, npm packages, or external libraries.
Dependency: Outside code your block needs in order to work. Dependencies can break, slow the page, or add supply-chain risk.
API key: A private credential for a service. If visitors can view it in page source, it is exposed.
Backend: Server-side code that can safely use secrets, validate requests, store data, and enforce permissions.
Sanitization: Cleaning input by removing or limiting unsafe markup before it is stored or rendered.
Escaping: Encoding output for the exact context where it appears, such as HTML text, attributes, URLs, CSS, or JavaScript.
Nonce: A one-time-ish WordPress token used to help confirm an action came from the intended screen or form.
XSS: Cross-site scripting: an injection bug where attacker-controlled code runs in a visitor’s browser.
CSP: Content Security Policy, a browser security header that can reduce script risk but does not replace fixing unsafe code.
Rollback: The exact way to undo the block if it breaks layout, behavior, tracking, or trust.

Resources and sources

Keep the safety pass connected to the rest of the Academy

CSS Scoping ChecklistUse the toolkit hub for scoping, website QA, mobile QA, accessibility QA, SEO QA, and performance QA assets. Codex Safety ChecklistReview secrets, permissions, approval, and rollback before real site changes. Codex Prompt BuilderTurn this checklist into a scoped review or build prompt. WordPress.org Custom HTML block docsOfficial block behavior, role capability notes, and editor details. WordPress escaping handbookContext-aware output escaping guidance for WordPress developers. OWASP XSS Prevention Cheat SheetReference for dangerous contexts, sanitization, encoding, and XSS prevention.

FAQ

Common WordPress Custom HTML safety questions

Is WordPress Custom HTML safe?

It can be safe for simple front-end content and tools when CSS is scoped, JavaScript is isolated, no secrets are exposed, and the block is tested in draft or staging. It is not the right place for private data, payments, logins, or server-trusted actions.

Can I use JavaScript in a WordPress Custom HTML block?

On self-hosted WordPress, users with the right capability can usually add scripts, but roles, hosts, security plugins, WordPress.com plans, and sanitization rules can strip or block script tags. Keep JavaScript small, local to the wrapper, and tested after saving.

Can I paste iframe embeds?

Sometimes. Prefer the native WordPress Embed block when it supports the provider. For iframes, review the source, permissions, dimensions, mobile behavior, loading cost, privacy expectations, and whether WordPress or your plan allows the tag.

Can I collect form submissions with Custom HTML?

A form UI can live in Custom HTML, but real submission handling needs a trusted endpoint, consent copy, spam controls, validation, privacy review, and error handling. A native Form block or approved form plugin is usually safer for beginners.

Can I use API keys in Custom HTML?

No private API key belongs in browser-visible HTML or JavaScript. Visitors can inspect source and network requests. Use server-side code, environment variables, or an approved provider integration instead.

Why did WordPress strip my HTML?

WordPress may remove disallowed tags or attributes based on role capabilities, WordPress.com plan rules, security plugins, or the editor context. Tags such as script, style, iframe, form, object, and embed are common places to see stripping.

Why does it work in preview but not live?

Preview and live pages can differ because of theme CSS, caching, minification, security headers, role-based sanitization, plugin conflicts, missing assets, or scripts running before the saved markup exists. Test after saving while logged out too.

WordPress Custom HTML Safety Checklist