React Cookie Management Library

8.1.0 · active · verified Sun Apr 19

react-cookie is a utility library for React applications that provides a universal (isomorphic) solution for managing browser cookies, enabling consistent cookie handling across both client-side and server-side rendering (SSR) environments. Its current stable version is 8.1.0, with frequent updates addressing dependencies and minor improvements, typically on a monthly cadence for patch releases and less frequently for minor/major versions as features or breaking changes are introduced. Key differentiators include its integration with the underlying `universal-cookie` library for core logic, offering React-specific hooks (`useCookies`) and a provider pattern (`CookiesProvider`) for easy consumption within React component trees. It simplifies reading, setting, and removing cookies by abstracting away the browser's `document.cookie` API and Node.js server request headers, making it particularly useful for applications requiring robust cookie management in an SSR context.

Common errors

```
Error: useCookies must be used within a CookiesProvider
```
cause The `useCookies` hook was called outside the context of a `CookiesProvider` component.

fix Wrap your component tree, or at least the components using `useCookies`, with `CookiesProvider` at a higher level in your application.
```
TypeError: Cannot read properties of undefined (reading 'useCookies')
```
cause Incorrect named import for `useCookies` or `react-cookie` library not correctly installed/imported.

fix Ensure you are using `import { useCookies } from 'react-cookie';` and `react-cookie` is listed in your `package.json` and `node_modules`.
```
Argument of type 'string | object' is not assignable to parameter of type 'string'.
```
cause Attempting to pass a non-string value directly to `setCookie` without allowing `react-cookie` to stringify it, or a TypeScript type mismatch.

fix The `setCookie` method automatically stringifies objects, so ensure you're providing the expected type or explicitly cast if TypeScript complains without real reason. If the `value` is an object, `react-cookie` handles serialization.

Warnings

breaking `react-cookie` v3.0+ requires React.js >= 16.3.0 due to its reliance on the new Context API and `forwardRef`.
Fix: Ensure your project uses React.js version 16.3.0 or higher. For older React versions (15.x), use `react-cookie` versions 0.0-2.2.
gotcha Cookies with the `httpOnly` flag cannot be accessed or modified from client-side JavaScript, including through `react-cookie` hooks or methods.
Fix: Understand that `httpOnly` cookies are exclusively for server-side access to enhance security. Do not attempt to manipulate them from the browser. For client-accessible data, avoid the `httpOnly` flag.
breaking When using Server-Side Rendering (SSR), the `cookies` prop *must* be set on `CookiesProvider` using `req.universalCookies` or a `new Cookies(cookieHeader)` instance to correctly hydrate the server's cookie state.
Fix: On the server, pass the cookie instance obtained from the incoming request (e.g., `req.universalCookies` if using `universal-cookie-express`, or `new Cookies(req.headers.cookie)`) to the `CookiesProvider` prop, like `<CookiesProvider cookies={serverCookiesInstance}>`.
gotcha The `useCookies` hook's `dependencies` array (optional) dictates when the component re-renders. If unspecified, it will re-render on *any* cookie change, which can lead to unnecessary re-renders.
Fix: Always specify the exact cookie names your component depends on in the `dependencies` array to optimize performance and prevent excessive re-renders, e.g., `useCookies(['my-specific-cookie'])`.

Install

npm install react-cookie npm
yarn add react-cookie yarn
pnpm add react-cookie pnpm

Imports

useCookies
wrong:
```
const useCookies = require('react-cookie').useCookies;
```
correct:
```
import { useCookies } from 'react-cookie';
```
Primary hook for accessing and modifying cookies. CommonJS `require` is generally discouraged in modern React projects using ESM.
CookiesProvider
wrong:
```
import CookiesProvider from 'react-cookie';
```
correct:
```
import { CookiesProvider } from 'react-cookie';
```
Provides a cookie context to all children. It's a named export, not a default export.
withCookies
wrong:
```
import withCookies from 'react-cookie';
```
correct:
```
import { withCookies } from 'react-cookie';
```
Higher-order component (HOC) for injecting cookies into class components. Named export. Less common in functional components due to `useCookies` hook.
Cookies
wrong:
```
import UniversalCookies from 'react-cookie/universal-cookie';
```
correct:
```
import { Cookies } from 'react-cookie';
```
Refers to the underlying `universal-cookie` instance for imperative access outside React components. It's a re-export from `universal-cookie`.

Quickstart

This quickstart demonstrates setting up `CookiesProvider` and using the `useCookies` hook to interact with a cookie named 'my-cookie-name'.

import React from 'react';
import { CookiesProvider, useCookies } from 'react-cookie';

function MyComponent() {
  const [cookies, setCookie, removeCookie] = useCookies(['my-cookie-name']);

  const handleSetCookie = () => {
    setCookie('my-cookie-name', 'hello-world', { path: '/', maxAge: 3600 });
  };

  const handleRemoveCookie = () => {
    removeCookie('my-cookie-name', { path: '/' });
  };

  return (
    <div>
      <h1>Cookie Value: {cookies['my-cookie-name'] || 'None Set'}</h1>
      <button onClick={handleSetCookie}>Set Cookie</button>
      <button onClick={handleRemoveCookie}>Remove Cookie</button>
      <p>This component demonstrates how to use `useCookies` to read, set, and remove cookies. The `CookiesProvider` makes the cookie context available throughout your app.</p>
    </div>
  );
}

export default function App() {
  return (
    <CookiesProvider>
      <MyComponent />
    </CookiesProvider>
  );
}

view raw JSON →