HTMLScriptElement: src property

Value

Getting the property returns a string containing the element's script URI.

Setting the property accepts either a TrustedScriptURL object or a string.

Exceptions

TypeError

Thrown if the property is set with a string when Trusted Types are enforced by a CSP and no default policy is defined. This is also thrown if the fetched URL cannot be successfully parsed as its indicated type, such as a module or importmap.

Description

The src property represents the URL of an external script. If set, scripts provided via the text properties text, textContent, or innerText, are ignored.

Security considerations

The src property is used to load and run external scripts. The fetched script is run in the context of the current page, and can hence do anything that your own website code can do (even if the URL is not same-origin with your site). If the input is provided by a user, this is a possible vector for cross-site scripting (XSS) attacks.

It is extremely risky to accept and execute arbitrary URLs from untrusted origins. A website should control what scripts that are allowed to run using a Content Security Policy (CSP) with the script-src directive (or a fallback defined in default-src). This can restrict scripts to those from the current origin, or a specific set of origins, or even particular files.

If you're using this property and enforcing trusted types (using the require-trusted-types-for CSP directive), you will need to always assign TrustedScriptURL objects instead of strings. This ensures that the input is passed through a transformation function, which has the chance to reject or modify the URL before it is injected.

Even if the resource is trusted by your website, it may still be compromised in a supply chain attack. To mitigate against this kind of attack you should use the subresource integrity feature.

Examples

Using TrustedScriptURL

To mitigate the risk of XSS, we should always assign TrustedScriptURL instances to the src property. We also need to do this if we're enforcing trusted types for other reasons and we want to allow some script sources that have been permitted (by CSP: script-src).

Trusted types are not yet supported on all browsers, so first we define the trusted types tinyfill. This acts as a transparent replacement for the trusted types JavaScript API:

if (typeof trustedTypes === "undefined")
  trustedTypes = { createPolicy: (n, rules) => rules };

Next we create a TrustedTypePolicy that defines a createScriptURL() method for transforming input strings into TrustedScriptURL instances.

For the purpose of this example we'll assume that we want to allow a predefined set of URLs in the scriptAllowList array and log any other scripts.

const scriptAllowList = [
  /*Some list of allowed URLs */
];
const policy = trustedTypes.createPolicy("script-url-policy", {
  createScriptURL(input) {
    if (scriptAllowList.includes(input)) {
      return input; // allow the script
    }
    console.log(`Script not in scriptAllowList: ${input}`);
    return ""; // Block the script
  },
});

Next we'll create the script element to which we will assign the value and get a handle to the element.

<script id="el" type="text/javascript"></script>

// Get the script element we're injecting the code into
const el = document.getElementById("el");

Then we use the policy object to create a trustedScript object from the potentially unsafe input string, and assign the result to the element:

// The potentially malicious string
// We won't be including untrustedScript in our scriptAllowList array
const untrustedScript = "https://evil.example.com/naughty.js";

// Create a TrustedScriptURL instance using the policy
const trustedScriptURL = policy.createScriptURL(untrustedScript);

// Inject the TrustedScriptURL (which contains a trusted URL)
el.src = trustedScriptURL;

Reading the src property

This example shows how you can read the src property for the two script elements below, assuming page URL is https://example.com.

<script id="script-with-src" type="module" src="/main.js"></script>
<script id="script-without-src" type="module"></script>

The code reads each of the script elements and logs the output of the src property.

const scriptWithSrc = document.getElementById("script-with-src");
console.log(scriptWithSrc.src); // Output: "https://example.com/main.js"
const scriptWithoutSrc = document.getElementById("script-without-src");
console.log(scriptWithoutSrc.src); // Output: ""

Specifications

Browser compatibility