Iframe Sandbox Attribute Guide | ToolBoxes

Embedding untrusted HTML in a page—whether for a live preview, a third-party widget, or user-submitted content—carries significant risk. Without restrictions, an embedded frame can redirect the parent page, access cookies, trigger downloads, or run popup windows. The sandbox attribute on <iframe> elements applies the principle of least privilege, granting only the permissions an embedded document genuinely needs.

The Sandbox Security Model

When you add the sandbox attribute to an iframe, the embedded document is placed under the strictest possible restrictions. It cannot:

Submit forms
Run scripts
Navigate the parent page
Access same-origin resources (cookies, localStorage, DOM)
Open popups or new windows
Trigger modal dialogs (alert, prompt, confirm)
Use the pointerlock, autoplay, or payment APIs

Every permission must be explicitly granted through a token added to the sandbox value. This deny-by-default model ensures that forgetting a restriction is safe—only forgetting to grant a permission causes functionality to break, and breakage is visible.

<!-- Maximum lockdown: no scripts, no forms, no navigation -->
<iframe sandbox src="https://untrusted.example.com/embed"></iframe>

<!-- Allow scripts but nothing else -->
<iframe sandbox="allow-scripts" src="/preview/user-code"></iframe>

<!-- Allow scripts and same-origin access -->
<iframe sandbox="allow-scripts allow-same-origin" src="/widget"></iframe>

Sandbox Token Reference

Each token grants a specific capability. Combine multiple tokens as a space-separated list.

Token	Grants	Risk Level
`allow-scripts`	JavaScript execution	High — scripts combined with same-origin can escape the sandbox
`allow-same-origin`	Access to parent's cookies and storage	High — see warning below
`allow-forms`	Form submission	Medium — forms can send data to external servers
`allow-popups`	Opening `window.open` links	Medium — popups escape sandbox restrictions
`allow-popups-to-escape-sandbox`	Popups inherit parent privileges	Low — popups get full permissions
`allow-top-navigation`	Navigate the parent page	High — can redirect users away
`allow-top-navigation-by-user-activation`	Navigate parent only on user click	Medium — safer than unrestricted navigation
`allow-downloads`	Download files	Low
`allow-modals`	Use alert/confirm/prompt	Low
`allow-presentation`	Use Presentation API	Low

The Scripts + Same-Origin Trap

The most critical security consideration: never combine allow-scripts and allow-same-origin on the same iframe that loads untrusted content. When both tokens are present, the embedded document can use JavaScript to remove its own sandbox attribute from the parent's DOM, effectively escaping all restrictions.

This combination is safe only when the embedded content is fully trusted (such as a same-domain widget) or when the iframe's src is a data URI or blob URL that has no origin to align with the parent.

For HTML preview tools—the exact use case that demands both tokens—you must use additional defenses:

Set the iframe's srcdoc attribute instead of a URL. Content in srcdoc is treated as a unique opaque origin that never matches the parent, even with allow-same-origin.
Use a separate subdomain with its own origin. Serve preview content from preview.yourapp.com while the parent runs on app.yourapp.com.
Deploy Content Security Policy (CSP) headers within the iframe to further restrict script behavior.

Practical Examples

Secure live preview for a code playground:

<iframe
  sandbox="allow-scripts"
  srcdoc="<html><body><h1>Hello</h1><script>document.body.style.color='red'</script></body></html>"
></iframe>

Here, srcdoc ensures the content has a unique origin. Scripts run but cannot access the parent page. No allow-same-origin token is needed.

Embedding a trusted internal widget:

<iframe
  sandbox="allow-scripts allow-same-origin allow-forms"
  src="/widgets/analytics-dashboard"
></iframe>

Safe because the source is same-origin and fully controlled.

Embedding a third-party video player:

<iframe
  sandbox="allow-scripts allow-presentation"
  src="https://videos.example.com/embed/abc123"
></iframe>

Scripts run for playback, but no forms, no navigation, no same-origin access.

Testing Your Sandbox Configuration

Always test sandbox configurations with deliberate escape attempts. Create a test page that tries parent.document, top.location.href, and window.open to verify that restrictions hold. Browser developer tools show the active sandbox flags in the iframe's security properties.

For quick sandbox attribute generation and testing, the HTML Preview tool renders code snippets in a sandboxed environment with configurable permissions.