Custom HTML Block

The Custom HTML block lets you add raw code — HTML, CSS, and JavaScript — directly into page content. It renders that code inline, giving you a way to include functionality that doesn’t have a dedicated block.

Why use the Custom HTML block

Use the Custom HTML block when you need to add code that isn’t supported by an existing block or plugin. This is an advanced block. It’s best suited to more technical editors who understand the code they’re adding and the impact it can have on a page. Because the block outputs code directly, mistakes or conflicts can affect how a page looks or behaves.

It’s most often used to:

  • Embed third-party widgets or services using a <script> tag
  • Add an <iframe> to display external content
  • Insert small, self-contained snippets of custom markup

Reach for a dedicated block or vetted plugin first. The Custom HTML block is the right choice only when no purpose-built option exists and you’re confident in the code you’re adding.

How to use the block

Start by adding the Custom HTML block to the page. Learn how to add blocks.

Once the block is added, editors typically:

  • Click Edit HTML to open the code editor
  • Enter code in the appropriate tab (HTML, and where available, CSS or JavaScript)
  • Review how the block renders in the editor

Entering your code

  1. With the block added, click Edit HTML.
  2. A popup modal opens with up to three tabs: HTML, CSS, and JavaScript.
  3. Enter your code in the tab that matches its type.
  4. Click Update.
  5. Once code is entered, the block renders directly in the editor. To make changes later, select the block and click Edit code in the block toolbar to reopen the modal.

Who can edit the CSS and JavaScript tabs

The CSS and JavaScript tabs are only available to users with permission to add unfiltered code — in most cases, administrators. Other roles will see the HTML tab only.

For users without that permission, code such as <script> and <iframe> is removed automatically when the page is saved or updated. If you’re adding embeds or scripts and the CSS or JavaScript tabs aren’t showing, you likely don’t have the required permission — check with an administrator.

Notes

  • On WordPress versions earlier than 7.0, the Custom HTML block contains a single field for entering all custom code, rather than the separate HTML, CSS, and JavaScript tabs.
  • When a user lacks permission to add unfiltered code, WordPress sanitizes the block’s content on save, stripping disallowed tags like <script> and <iframe>. The CSS and JavaScript tabs are not shown in this case.

Block toolbar

When the block is selected, the toolbar includes the standard block controls along with:

  • Edit code: Reopens the code editor modal so you can update your HTML, CSS, or JavaScript.

There are no other Custom HTML–specific controls in the toolbar.

Block settings

The Custom HTML block does not include additional settings in the block settings sidebar.

All configuration happens through the code editor modal. The block’s behavior is determined entirely by the code you enter.

Accessibility and content structure

Because this block outputs raw code, accessibility depends entirely on the code you add. The block does not add or correct markup for you.

To keep content accessible:

  • Make sure any markup you add uses correct, semantic HTML
  • Provide accessible labels, alt text, or descriptions where your code includes images, controls, or embedded content
  • Confirm that embedded third-party content meets accessibility standards

The block won’t catch accessibility issues in your code, so the responsibility sits with the editor adding it.

Tips for editors

Know what your code does

Only use this block when you understand the code you’re adding and why. If you’re unsure whether a <script> or <iframe> is safe or necessary, check with a developer before publishing.

Always check the front end

Incorrectly entered code, or code that conflicts with other code on the page, can cause a range of errors — from broken layouts to scripts that don’t load. The editor view doesn’t always reflect the final result, so always review the published page on the front end to confirm everything works as expected.

Prefer a dedicated block when one exists

If a block or vetted plugin already handles what you need, use it. Those options are easier to maintain, more accessible by default, and less likely to break than custom code.

Keep snippets small and self-contained

The more code you add, the harder it is to troubleshoot when something goes wrong. Keep each block focused on a single purpose.

  1. WordPress.org Custom HTML block documentation. Please note that your block may have customizations affecting the functionality, appearance, and settings.