---
title: "useCookie 用法與示例"
description: "useCookie 是一個依 key 來存儲、更新與刪除瀏覽器 cookie 的 React hook，回傳該值以及 update 和 refresh 函式，並支援 js-cookie 的選項。"
canonical: https://reactuse.com/zh-Hant/state/usecookie/
---

# useCookie

有助於在 CookieStore 中存儲、更新和刪除值的 hook

:::note
使用相同鍵的多個 `useCookie` 實例會在同一標籤頁內保持同步：在一個組件中呼叫 `updateCookie` 會自動讓其他組件重新渲染。（舊版本不會——需要手動廣播；現在不再需要了。）
:::


`useCookie` 提供響應式的瀏覽器 cookie 讀寫。它回傳一個元組，包含當前 cookie 值（或 `null`）和一個更新 cookie 的函式。支援設定 cookie 的各種屬性（過期時間、路徑、域名、安全性等）。刪除 cookie 可透過將值設為 `null` 或 `undefined`。

### 使用場景

- 讀取和寫入使用者偏好設定到 cookie
- 管理認證 token 或工作階段資訊
- 建構需要 cookie 存取的同意管理或功能旗標系統

### 注意事項

- **SSR 安全**：在伺服器端渲染時回傳 `null`。伺服器上不會存取 `document.cookie`。
- **同標籤頁同步**：在一個組件中更新 cookie 會自動讓同一標籤頁內使用相同鍵的其他 `useCookie` 實例重新渲染。cookie 沒有原生的跨標籤頁事件，因此**不會**跨標籤頁傳播。
- **Cookie 屬性**：支援所有標準 cookie 屬性，包括 `expires`、`path`、`domain`、`secure`、`sameSite` 和 `httpOnly`。
- **相關 hooks**：另請參閱 `useLocalStorage` 和 `useSessionStorage` 用於 Web Storage API 的替代持久化方案。

## Usage

```tsx live
function Demo() {
    const defaultOption = {
    path: "/",
  };
  const cookieName = "cookie-key";
  const [cookieValue, updateCookie, refreshCookie] = useCookie(
    cookieName,
    defaultOption,
    "default-value",
  );

  const updateButtonClick = () => {
    updateCookie("new-cookie-value");
  };

  const deleteButtonClick = () => {
    updateCookie(undefined);
  };

  const change = () => {
    if ("cookieStore" in window) {
      const store = window.cookieStore as any;
      store.set({ name: cookieName, value: "changed" });
    }
    else {
      document.cookie = `${cookieName}=changed; path=/`;
    }
  };

  return (
    <div>
      <p>點擊按鈕以更新或清除 cookie</p>
      <p color="blue">cookie：{cookieValue || "無值"}</p>
      <button onClick={updateButtonClick}>更新 cookie</button>
      <button onClick={deleteButtonClick}>清除 cookie</button>
      <button onClick={change}>
        通過其他方法更改 cookie
      </button>
      <button onClick={refreshCookie}>刷新 cookie</button>
    </div>
  );
}

```

## 同標籤頁同步

使用相同 cookie 鍵的兩個組件會在同一標籤頁內保持同步——在任意一個面板點擊按鈕，另一個面板會立即更新，無需手動廣播，也無需重新載入：

```tsx live noInline
function CookiePanel({ label }) {
  const [value, updateCookie] = useCookie("shared-demo-cookie", { path: "/" }, "A");
  return (
    <div
      style={{
        border: "1px solid var(--sl-color-gray-5, #ccc)",
        borderRadius: 6,
        padding: 12,
        marginBottom: 8,
      }}
    >
      <strong>{label}</strong> 目前值：<code>{value ?? "(空)"}</code>
      <div style={{ display: "flex", gap: 8, marginTop: 8 }}>
        <button onClick={() => updateCookie("A")}>Set A</button>
        <button onClick={() => updateCookie("B")}>Set B</button>
        <button onClick={() => updateCookie("C")}>Set C</button>
        <button onClick={() => updateCookie(undefined)}>Clear</button>
      </div>
    </div>
  );
}

function Demo() {
  return (
    <div>
      <p>在任意一個面板點擊按鈕——另一個面板會在同一標籤頁內同步更新：</p>
      <CookiePanel label="組件 A" />
      <CookiePanel label="組件 B" />
    </div>
  );
}

render(<Demo />);
```

%%API%%