cookies.set()

Sets a cookie. This method is equivalent to issuing an HTTP Set-Cookie header during a request to a URL.

To use this method, an extension must have the "cookies" permission and relevant host permissions. See cookie permissions for more details.

Syntax

let setting = browser.cookies.set(
  details               // object
)

Parameters

• details
  • : An object containing the details of the cookie you wish to set. It can have these properties:

    • domain {{optional_inline}}

      • : A string representing the domain of the cookie. If omitted, the cookie becomes a host-only cookie.

    • expirationDate {{optional_inline}}

      • : A number that represents the expiration date of the cookie as the seconds after the UNIX epoch. It can include milliseconds in the fractional part. If omitted, the cookie becomes a session cookie.

    • firstPartyDomain {{optional_inline}}

      • : A string representing the first-party domain with which the cookie is associated. This property must be supplied if the browser has first-party isolation enabled. See First-party isolation.

    • httpOnly {{optional_inline}}

      • : A boolean that specifies whether the cookie is marked as HttpOnly (true), or not (false). If omitted, it defaults to false.

    • name {{optional_inline}}

      • : A string representing the name of the cookie. If omitted, the name defaults to an empty string ("").

    • partitionKey {{optional_inline}}

      • : An object representing the storage partition to set the cookie in. Include this object to set a cookie in partitioned storage. This object contains:
        • topLevelSite {{optional_inline}}
          • : A string representing the first-party URL of the top-level site storage partition containing the cookie.

    • path {{optional_inline}}

      • : A string representing the path of the cookie. If omitted, this defaults to the path portion of the URL parameter.

    • sameSite {{optional_inline}}

      • : A {{WebExtAPIRef("cookies.SameSiteStatus")}} value that indicates the SameSite state of the cookie. If omitted, defaults to unspecified.

    • secure {{optional_inline}}

      • : A boolean that specifies whether the cookie is marked as secure (true), or not (false). If omitted, it defaults to false.

    • storeId {{optional_inline}}

      • : A string representing the ID of the cookie store in which to set the cookie. If omitted, the cookie is set in the current execution context's cookie store.

    • url

      • : A string representing the request-URI to associate with the cookie. This value can affect the default domain and path values of the created cookie. If host permissions for this URL are not specified in the manifest file, the method call fails.

    • value {{optional_inline}}

      • : A string representing the value of the cookie. If omitted, the value defaults to an empty string ("").

Return value

A Promise fulfilled with a {{WebExtAPIRef('cookies.Cookie')}} object containing details about the set cookie.

If there is more than one cookie with the same name for a URL, the cookie with the longest path is returned. For cookies with the same path length, the cookie with the earliest creation time is returned.

[!NOTE] Before Firefox 133, when there was more than one cookie with the same name, Firefox returned the cookie with the earliest creation time.

If the requested cookie is invalid or the call otherwise fails, the promise is rejected with an error message.

[!NOTE] Before Firefox 145, invalid cookies were created.

Examples

This example sets a cookie for the document hosted by the active tab:

let getActive = browser.tabs.query({ active: true, currentWindow: true });
getActive.then(setCookie);

function setCookie(tabs) {
  browser.cookies.set({
    url: tabs[0].url,
    name: "favorite-color",
    value: "red",
  });
}

{{WebExtExamples}}

Browser compatibility

{{Compat}}

[!NOTE] This API is based on Chromium's chrome.cookies API. This documentation is derived from cookies.json in the Chromium code.