What Is a Sandboxed Iframe?

A sandboxed iframe is an embedded browser document with extra restrictions applied by the iframe's sandbox attribute. With an empty sandbox value, the browser starts from a restrictive baseline; individual allow-* tokens return only the capabilities the embedded content needs. For an HTML preview, the safest useful design is not “trust the code.” It is “give the preview a separate boundary, add the minimum permissions, and keep secrets out of the experiment.”

What changes when an iframe is sandboxed?

An ordinary iframe creates a nested browsing context. Same-origin policy, Permissions Policy, Content Security Policy, and the framed site's own headers still matter, but the frame is not automatically stripped of every browser capability.

Adding sandbox asks the browser to impose an additional set of restrictions. The WHATWG HTML Standard defines the attribute as an unordered, space-separated set of tokens. The absence of a token keeps its corresponding sandbox restriction in place; adding a token lifts a particular restriction.

That direction is easy to misread:

```html

<iframe sandbox srcdoc="<p>Static preview</p>"></iframe>

```

This is the restrictive form. It does not mean “no sandbox options selected.” It means the sandbox is active and none of its optional capabilities have been restored.

```html

<iframe

sandbox="allow-scripts allow-forms"

srcdoc="<button type='button'>Run</button>">

</iframe>

```

This version permits scripts and form behavior while leaving other restrictions in place. The exact security outcome still depends on where the content comes from and what the surrounding application exposes.

Which restrictions apply by default?

The full standard contains more detail than one checklist, but these categories explain most preview behavior.

The MDN iframe reference lists the current tokens and explains what each one restores. Check that reference instead of copying an old token list into a long-lived security control.

What do the common allow tokens restore?

Think of each token as a capability decision, not a convenience switch.

Some tokens interact. Reviewing them one at a time is necessary but not sufficient. The origin of the framed document, whether it is srcdoc or a remote URL, the host's Content Security Policy, and any message bridge between frame and parent all affect the boundary.

The diagram describes a permission boundary. It does not claim that any token set makes arbitrary code harmless.

Why does an opaque origin matter?

Without allow-same-origin, sandboxed content is treated as coming from a special origin that fails normal same-origin checks. Developers often call this an opaque or unique origin.

For an inline srcdoc preview, that separation is valuable. The preview can render a document without being treated as the same application origin as the editor page. It cannot simply reach into the parent's DOM or read same-origin storage as though it were another component of the host.

Opaque origin does not mean “offline” or “network disabled.” If scripts are allowed, preview code may still make network requests that browser policies and the destination permit. It can use CPU and memory, manipulate its own DOM, and communicate through channels the host deliberately exposes. The boundary reduces authority; it does not certify the code.

MDN warns particularly about combining allow-scripts and allow-same-origin when the embedded content is same-origin and can remove its own sandbox attribute. The important lesson is contextual: do not restore both capabilities merely because an example fails without them.

How does the ClockTools preview configure its sandbox?

The live ClockTools real-time HTML editor builds the preview with srcdoc. When JavaScript is enabled, its iframe sandbox value is:

allow-scripts allow-forms allow-modals

The implementation intentionally omits allow-same-origin, allow-popups, top-navigation permissions, and download permission. The interface labels the preview as an opaque sandbox, making the origin decision visible rather than hiding it in source code.

That configuration supports common teaching examples: scripts can update the preview, forms can exercise browser validation and submission behavior, and modal examples can run. It does not turn unknown code into trusted code. The editor's own guidance therefore tells users to avoid secrets and review unfamiliar scripts.

The page also captures console messages and exposes a document-check panel. Those are observability features, not sandbox permissions. A console panel helps explain a failure; it does not prevent a request. A structural check can flag a missing label; it does not conduct a complete security review.

What did a capability check show?

I inspected the rendered preview element in the live ClockTools workspace rather than relying only on marketing text.

The iframe title was “Live HTML preview,” which also gives assistive technology a purpose label for the embedded document.

This inspection confirms the configured boundary at that moment. It does not prove that every possible script is safe, and it does not replace a review of the message bridge, external-resource handling, Content Security Policy, or future code changes.

Which token combinations deserve extra caution?

Use a threat-based review instead of a universal token recipe.

allow-scripts plus allow-same-origin

This pair can seriously weaken isolation when the embedded document is same-origin and can affect its embedding conditions. If both are required, serve untrusted content from a deliberately separate origin and analyze the escape paths rather than treating the attribute as the only boundary.

Forms plus network access

allow-forms restores submission, but scripts and ordinary HTML elements may also send requests in other ways. Never put credentials, private customer data, or bearer tokens into an untrusted preview and assume the sandbox will contain them.

Popups plus escape behavior

allow-popups lets a frame open a new browsing context. allow-popups-to-escape-sandbox lets the new context avoid inherited sandbox flags. That can be useful for a deliberately isolated advertisement or external link, but it expands the review surface.

Top navigation

Top-navigation permissions allow the frame to replace the host page under defined conditions. A code playground rarely needs that. If navigation is part of the lesson, consider intercepting and displaying the destination instead of granting the preview control over the top-level page.

What can a sandbox not protect?

A sandbox is one browser mechanism, not a complete hostile-code platform.

• It does not stop a user from opening the same content directly outside the frame.
• It does not guarantee that allowed scripts will be fast, polite, or free of infinite loops.
• It does not automatically block every network request.
• It does not sanitize HTML or prove that a URL is safe.
• It does not secure secrets already placed inside the preview.
• It does not replace server-side validation for real forms.
• It does not validate accessibility, semantics, or cross-browser behavior.
• It does not protect another service that accepts a request from the preview.

The boundary also changes over time as browsers and standards evolve. Feature behavior should be tested in the browsers the audience actually uses, and the token list should be reviewed against current specifications.

How should you design a browser code preview?

Start with the empty sandbox attribute, then add one capability at a time. For each addition, create a small acceptance test and a corresponding abuse test.

Keep the parent-frame message protocol narrow. Validate the sender, message shape, and allowed commands. Do not accept arbitrary code or navigation instructions through a generic “execute” message unless that is the explicitly isolated product you intend to build.

Offer a JavaScript-off mode for static inspection. Add stop, reset, or reload controls for runaway examples. Surface console errors without mirroring sensitive parent data into the frame. Treat external stylesheets and scripts as network dependencies whose hosts and future contents are outside the editor's control.

For a focused experiment, the real-time HTML editor exposes responsive widths, console capture, checks, and its opaque sandbox state. For release work involving packages, servers, credentials, tests, or deployment, move the code into a local repository and use a fuller development and security-review workflow.