Skip to main content

The sandbox Attribute

You have met sandbox briefly in earlier lessons. This one is the full story. The sandbox attribute puts an iframe in a locked room: by default the embedded page can do almost nothing, and you unlock only the specific powers it needs. It is one of the strongest tools HTML gives you, and it is only one attribute.

What You Will Learn​

  • What an empty sandbox takes away
  • What each permission token adds back
  • The allow-scripts plus allow-same-origin trap
  • How to choose the smallest set of permissions
  • Where sandbox does and does not help
  • How to apply a sandbox with a header

The Big Idea​

Most security settings say what to block. sandbox flips this: everything is blocked until you allow it. That is called a deny-by-default design, and it is why sandbox is safer than lists of rules you might forget to update.

index.html
<!-- Everything blocked -->
<iframe src="preview.html" title="Preview" sandbox></iframe>

<!-- Only scripts allowed -->
<iframe src="https://widgets.example.net/calc" title="Calculator"
sandbox="allow-scripts"></iframe>

<!-- Several permissions, space separated -->
<iframe src="https://pay.example.net/form" title="Payment"
sandbox="allow-scripts allow-same-origin allow-forms allow-popups"></iframe>

What an Empty sandbox Does​

Adding the bare attribute sandbox (or sandbox="") applies all restrictions. The embedded page:

  • cannot run JavaScript,
  • cannot submit forms,
  • cannot open popups or new tabs,
  • cannot show alert and similar boxes,
  • cannot navigate your whole page to another address,
  • cannot start downloads,
  • cannot use plugins, or lock the pointer,
  • and is treated as coming from a unique, empty origin, so it cannot use its own cookies or localStorage, and cannot be treated as the same site as anything else.

It can still show HTML and CSS, load images, and play media. That is why an empty sandbox suits previews and static content.

The Permission Tokens​

You add powers back with space-separated tokens. Unknown tokens are ignored, so a typo silently does nothing. Always test.

TokenWhat it allowsThink twice when
allow-scriptsRunning JavaScriptCombined with allow-same-origin (see below)
allow-same-originKeeping its real origin, so its own cookies and storage workContent is from your own site
allow-formsSubmitting formsThe page could show a fake form
allow-popupswindow.open and links with target="_blank"The popups are not trusted
allow-popups-to-escape-sandboxPopups open without the sandboxAlmost always; use only for trusted providers
allow-modalsalert, confirm, promptThey can be used to annoy or mislead
allow-top-navigationNavigating the whole pageNearly always; it enables page hijacking
allow-top-navigation-by-user-activationThe same, but only right after a clickA safer choice if you need top navigation
allow-downloadsStarting downloadsThe source is unknown
allow-pointer-lockLocking the pointer (games and 3D)Rarely needed

Browsers add new tokens from time to time. The list on MDN is the complete, current reference.

Same origin, and an empty origin​

The word "origin" comes from HTML Security Basics: scheme, host, and port. Without allow-same-origin, the framed page gets an opaque origin that matches nothing, so:

  • it cannot read its own cookies or localStorage, and many apps break,
  • requests from it to its own server count as cross-origin,
  • and, importantly, if it is your content, it is also cut off from your site's origin.

For a page from another site, adding allow-same-origin returns that site's origin to it, not yours. It still cannot touch your page. That is why it is a common, reasonable choice for video and payment widgets.

The Trap: allow-scripts Plus allow-same-origin​

If the framed page comes from your own origin, and you add both allow-scripts and allow-same-origin, the page's script can reach its own iframe element in the parent, delete the sandbox attribute, and reload itself with no restrictions. The sandbox then protects nothing.

<!-- Same-origin content: do not do this -->
<iframe src="/uploads/page.html" sandbox="allow-scripts allow-same-origin"></iframe>

What to do instead:

  1. Remove allow-same-origin if the content only needs to run scripts.
  2. Serve untrusted content from a separate domain, so even its "real origin" cannot touch your site. This is how many code-playground and user-content platforms work.
  3. Check the Permission Lab: tick both tokens and switch between "my own site" and another site to see the warning change.

Choosing the Smallest Set​

  1. Start with an empty sandbox.
  2. Load the page and read the Console. Browsers report blocked actions, such as "Blocked script execution" or "Blocked a frame from submitting a form".
  3. Add one token that fixes a real, needed feature.
  4. Repeat until the embed works. Stop there.
  5. Document why each token is there, with a short comment in your template.

The Scenario Picker tab gives you five realistic embeds to practise this.

Sandbox and the allow Attribute​

These are separate controls that work together:

AttributeControls
sandboxBroad page behaviours: scripts, forms, popups, navigation, origin
allowBrowser features: camera, microphone, geolocation, fullscreen, payment

A sandboxed frame can still be refused a feature that allow does not grant. Use both. Features are also controlled by Permissions-Policy headers, as covered in iFrame Security.

Sandbox as a Header​

The same idea exists as a Content Security Policy directive, set by a server. It applies to any page it is sent with, even when that page is not in a frame:

Content-Security-Policy: sandbox allow-scripts

This is useful for files that visitors upload, such as HTML or SVG. If the response carries this header, opening the file directly in a browser tab gets the same restrictions as a sandboxed frame. See Content Security Policy.

Where Sandbox Helps, and Where It Does Not​

It helps againstIt does not
Untrusted or third-party pages running scriptsStop a page from showing misleading content inside its rectangle
Frames submitting forms or opening popupsReplace escaping and sanitising visitor input (see XSS Basics)
Frames hijacking the whole pageHide the visitor's address from the embedded host (see referrerpolicy)
Uploaded files being opened as full pages (header form)Protect a page that is not in a frame, unless the CSP header is used
Embedded code reaching your originWork in browsers too old to support it (very rare today)
info

Sandbox settings apply when the frame loads a page. If you change the sandbox attribute with JavaScript afterwards, the new setting takes effect only the next time the frame navigates, not instantly. Set it in the HTML, before the frame loads.

A Note on srcdoc​

An iframe with srcdoc takes its HTML from the attribute instead of loading a URL. With allow-same-origin, a srcdoc page gets your origin, which is dangerous if the HTML is untrusted. Without allow-same-origin, it gets an empty origin. Combine srcdoc with sandbox, and never add allow-same-origin for untrusted content.

Checking Your Setup​

  1. Open DevTools and the Console. Look for lines that begin "Blocked" or "Ignored", which show what the sandbox stopped. A typo in a token name may appear as an unrecognised value.
  2. Open Elements, and check that each third-party frame has a sandbox attribute. Hover it to see the exact string.
  3. Test every feature of the embed: playing, paying, logging in, resizing.
  4. For same-origin content, search your code for allow-scripts allow-same-origin together.

Best Practices​

  1. Sandbox every third-party and visitor-supplied frame.
  2. Start empty, then add one token at a time.
  3. Never combine allow-scripts and allow-same-origin for content from your own origin.
  4. Avoid allow-top-navigation. If you need it, use the by-user-activation version.
  5. Avoid allow-popups-to-escape-sandbox unless a trusted provider requires it.
  6. Serve untrusted content from a separate domain.
  7. Use allow and Permissions-Policy for browser features.
  8. Follow each provider's documentation, and test after each provider update.
  9. Keep a short comment explaining each permission.

Quick Checklist​

  • Every third-party frame has a sandbox
  • Each token is there for a reason you can state
  • No frame from your origin has allow-scripts and allow-same-origin together
  • No allow-top-navigation unless it is truly needed
  • Untrusted content is on a separate domain
  • The Console shows no unexpected blocked actions
  • Uploaded HTML and SVG are served with a sandbox CSP header, or from another domain

Security and Privacy Notes​

  • Sandbox limits actions, not what the embedded host learns. The host still receives the request, the visitor's IP address, and a referrer unless you control that. Use referrerpolicy and click to load, as in iFrame Security.
  • An empty origin can break consent and login tools that rely on cookies. If an embed needs storage, you must grant allow-same-origin, and accept that trade-off.
  • Do not treat sandbox as the only layer. Keep browsers updated, and combine it with CSP and careful input handling.
  • Test with permission. Try these settings on your own pages and test pages, not other people's sites.

Global Audience Notes​

  • Payment and identity providers vary by country. Check each provider's current documentation for the sandbox set it supports, as these change.
  • Sandboxed embeds fail quietly. Visitors on a weak connection see an empty box. Offer a link to open the content in a new tab, and write a clear title in the page's language.
  • Older and uncommon browsers may not support newer tokens. The embed should degrade to a link, not break the page.

Common Mistakes to Avoid​

  1. Leaving out sandbox on a third-party frame.
  2. Adding every token "just in case".
  3. Combining allow-scripts and allow-same-origin on your own content.
  4. Mistyping a token, so it is silently ignored.
  5. Using allow-top-navigation for convenience.
  6. Assuming sandbox hides the visitor's information from the embedded host.
  7. Changing sandbox with JavaScript and expecting an instant effect.
  8. Giving srcdoc content allow-same-origin when it holds untrusted HTML.
  9. Forgetting allow for camera, microphone, or fullscreen features.
  10. Never re-testing after a provider changes its embed.

Practice Time​

  1. In the Permission Lab, turn off the sandbox. Which warning appears?
  2. Turn it back on with nothing ticked. Which row, if any, is not "Blocked"?
  3. Tick allow-scripts and allow-same-origin. Switch between your own site and another site. How does the warning change?
  4. Tick allow-top-navigation, then swap it for the by-user-activation token. What changes in the table?
  5. Complete all five scenarios in the Scenario Picker.
  6. Add a sandboxed frame to a test page, then open the Console to see which actions are blocked.
  7. Write the CSP header you would send with a folder of visitor-uploaded HTML files.
  8. Bonus: find every iframe on one of your own pages, and write down what each token is for.

Quick Recap​

Click a question to check your answer.

1. What does an empty sandbox do?

It blocks scripts, forms, popups, modals, top navigation, downloads, and plugins, and gives the page an empty origin.

2. How do you allow a specific power?

Add a token such as allow-scripts or allow-forms to the sandbox value, separated by spaces.

3. Why is allow-scripts plus allow-same-origin dangerous?

On content from your own origin, the page's script can remove its own sandbox attribute, so the sandbox is useless. For another site's content, it only gives that site its own origin back.

4. How do you choose permissions?

Start with an empty sandbox, read the Console's blocked messages, add one token for each needed feature, and stop when the embed works.

5. What is the difference between sandbox and allow?

sandbox controls broad page behaviours such as scripts, forms and navigation. allow controls browser features such as camera, microphone and fullscreen.

6. How can a server apply a sandbox?

With the Content-Security-Policy: sandbox ... header, which also protects uploaded files opened directly in a browser.

Key Takeaways​

  • sandbox is deny by default. Add back only what is needed.
  • An empty origin means no cookies or storage until allow-same-origin is added.
  • Never pair allow-scripts with allow-same-origin for your own content.
  • Avoid allow-top-navigation and allow-popups-to-escape-sandbox.
  • Sandbox plus allow, CSP, and referrerpolicy work as layers.
  • Test in the Console, and re-test when providers change.

Next up: noreferrer, where you will learn what a link tells the next site about where the visitor came from, and how to control it.