The sandbox attribute

How the sandbox works

Add sandbox to an iframe to lock it down. With no value, the framed page gets the strictest rules:

<iframe src="https://partner.example/ad" sandbox title="Ad"></iframe>

The framed page can still show HTML and CSS. It cannot run scripts, submit forms, open popups, or change the URL of your page. The browser also gives it a unique origin that matches no other origin. So it cannot read its own cookies or localStorage.

To give back a power, add its flag. Separate flags with spaces:

<iframe
  src="https://partner.example/widget"
  sandbox="allow-scripts allow-forms allow-popups"
  title="Partner widget"
></iframe>

The sandbox only removes powers. It cannot give a frame a power that headers or the browser already block.

Every flag

Flag	What it allows
allow-scripts	Run JavaScript. Without it, most modern apps show a blank page.
allow-same-origin	Keep the real origin. Without it, cookies, localStorage, and same-origin requests fail.
allow-forms	Submit forms. Without it, a form shows but sending it does nothing.
allow-popups	Open new windows or tabs with window.open() or target="_blank". Without it, these fail with no error.
allow-popups-to-escape-sandbox	Open popups without the sandbox. Without it, the new tab gets the same limits as the frame.
allow-modals	Use alert(), confirm(), prompt(), and print(). A <dialog> works without it.
allow-downloads	Start file downloads.
allow-top-navigation	Change the URL of the top page at any time.
allow-top-navigation-by-user-activation	Change the URL of the top page, but only after a click or tap.
allow-top-navigation-to-custom-protocols	Open links with non-HTTP schemes, such as mailto: or app links.
allow-storage-access-by-user-activation	Ask for access to its own cookies with the Storage Access API.
allow-pointer-lock	Use the Pointer Lock API, for example in games.
allow-orientation-lock	Lock the screen orientation.
allow-presentation	Start a presentation session on a second screen.

Use allow-top-navigation-by-user-activation in place of allow-top-navigation. A frame with the full flag can send your visitor to another site with no click.

The dangerous pair: allow-scripts and allow-same-origin

Do not use allow-scripts and allow-same-origin together when the framed page has the same origin as your page.

With both flags, the framed page can run a script and reach into your page. It can then remove the sandbox attribute from its own iframe and reload. After that, it runs with no sandbox at all.

<!-- Unsafe: same origin as the parent, both flags set -->
<iframe src="/user-content/123" sandbox="allow-scripts allow-same-origin"></iframe>

For content from users, serve it from a different origin, for example https://usercontent.your-site.com. Then the pair is much safer, because the origin check keeps the frame out of your page.

Sandbox flags for common embeds

Embed	Flags to start with
Static HTML preview	none (empty sandbox)
Code playground on its own origin	allow-scripts allow-modals
Third-party widget or form	allow-scripts allow-same-origin allow-forms allow-popups
Login or payment flow	allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox

Add one flag at a time and test. Open the browser console. Most sandbox blocks print a message that names the missing flag.

When the sandbox breaks a page

• Blank frame. The page needs JavaScript and allow-scripts is missing. See Blocked script execution and Blank iframe, no error.
• Login does not stick. allow-same-origin is missing, so the page cannot read its cookies. See Login doesn't stick in an iframe.
• Forms do nothing. allow-forms is missing. See Blocked form submission.
• Links do nothing. allow-popups is missing for target="_blank" links. See Blocked opening in a new window.
• The frame cannot move the top page. allow-top-navigation is missing. See Unsafe attempt to initiate navigation.
• "Open in new tab" shows a broken page. Add allow-popups-to-escape-sandbox so the new tab is not sandboxed.

A server can also sandbox its own page with the sandbox directive of Content-Security-Policy. The same flags apply.

Check the page first

Paste the framed URL into the iframe tester. If the server blocks framing, no sandbox flag can fix it.

To try flags on a live page, use the sandbox playground. Turn each flag on or off and see what the framed page can still do. The embed code generator then writes the iframe code with the flags you pick.

Sources

• HTML Standard: the sandbox attribute
• MDN: the iframe element. MDN documents the allow-storage-access-by-user-activation token. The HTML standard does not list it.
• MDN: Storage Access API