CookieStore: set() method

فهرست فصل‌ها دانلود آرشیوناشر

MDN Web Docs · نسخهٔ df622a2a1c1e · CC BY-SA 2.5 و مجوز جداگانهٔ ناشر برای نمونه‌کد

{{securecontext_header}}{{APIRef("Cookie Store API")}}{{AvailableInWorkers("window_and_service")}}

The **set()** method of the {{domxref("CookieStore")}} interface sets a cookie with the given name and value or options object.

Syntax

js-nolint
set(name, value)
set(options)

Parameters

This method requires one of the following:

  • name {{optional_inline}}
  • : A string with the name of the cookie.
  • value {{optional_inline}}
  • : A string with the value of the cookie.

Or

  • options {{optional_inline}}
  • : An object containing:
  • domain {{Optional_Inline}}
  • : A string containing the domain of the cookie. Defaults to null.
  • expires {{Optional_Inline}}
  • : A timestamp, given as {{glossary("Unix time")}} in milliseconds, containing the expiration date of the cookie. Defaults to null.
  • maxAge {{Optional_Inline}}
  • : A number representing the number of seconds until the cookie expires. A zero or negative number will expire the cookie immediately. If both expires and maxAge are set, the set() call fails with a TypeError. Defaults to null.
  • name
  • : A string with the name of a cookie.
  • partitioned {{Optional_Inline}}
  • : A boolean value that defaults to false. If set to true, the set cookie will be a partitioned cookie. See Cookies Having Independent Partitioned State (CHIPS) for more information.
  • path {{Optional_Inline}}
  • : A string containing the path of the cookie. Defaults to /.
  • sameSite {{Optional_Inline}}
  • : One of the following [SameSite](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) values: ["strict"](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#strict), ["lax"](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#lax), or ["none"](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#none).
  • value
  • : A string with the value of the cookie.

توجه: While the values can be set here and will be used internally, some browsers will only return name and value options from {{domxref("CookieStore.get()")}} and {{domxref("CookieStore.getAll()")}}.

Return value

A {{jsxref("Promise")}} that resolves with {{jsxref("undefined")}} when setting the cookie completes.

Exceptions

  • SecurityError {{domxref("DOMException")}}
  • : Thrown if the origin cannot be {{glossary("Serialization", "serialized")}} to a URL.
  • {{jsxref("TypeError")}}
  • : Thrown if:
  • Both the expires and maxAge properties are set.
  • Setting the cookie with the given name and value or options fails in any other way.

Examples

<!-- The examples don't work as live examples in MDN environment (due to unknown errors) -->

Setting a cookie with name and value

This example sets a cookie by passing a name and value of "cookie1" and "cookie1-value", respectively. The other properties of the cookie are set with default values, as defined in the [options](#options) parameter.

The code first waits for the cookie to be set: as this operation can fail, the operation is performed in a try...catch block and any errors are logged to the console. It then gets and logs the cookie that was just set.

js
async function cookieTest() {
  // Set cookie: passing name and value
  try {
    await cookieStore.set("cookie1", "cookie1-value");
  } catch (error) {
    console.log(`Error setting cookie1: ${error}`);
  }

  // Get the cookie and log its values
  const cookie = await cookieStore.get("cookie1");
  console.log(cookie);
}

Setting a cookie with options

This example sets a cookie by passing an options object with name, value, expires, and partitioned.

The code first waits for the cookie to be set: as this operation can fail, the operation is performed in a try...catch block and any errors are logged to the console. It then gets and logs the cookie that was just set.

js
async function cookieTest() {
  const day = 24 * 60 * 60 * 1000;
  const cookieName = "cookie2";
  try {
    // Set cookie: passing options
    await cookieStore.set({
      name: cookieName,
      value: `${cookieName}-value`,
      expires: Date.now() + day,
      partitioned: true,
    });
  } catch (error) {
    log(`Error setting ${cookieName}: ${error}`);
    console.log(error);
  }

  // Log the new cookie
  const cookie = await cookieStore.get(cookieName);
  console.log(cookie);
}

Setting cookies with the same name

These calls create two separate cookies because their paths differ:

js
await cookieStore.set({ name: "theme", value: "light", path: "/" });
await cookieStore.set({ name: "theme", value: "dark", path: "/docs" });

On a page under /docs/, {{domxref("CookieStore.getAll()", 'cookieStore.getAll("theme")')}} can retrieve both cookies. Calling cookieStore.set("theme", "blue") updates the cookie at the default path /, leaving the /docs cookie unchanged.

Specifications

{{Specifications}}

Browser compatibility

{{Compat}}