react-cookie

library8.1.0jsnpmunverified

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.

web-framework http-networking auth-security

npm install react-cookie

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-COOKIE

react-cookie

web-frameworkjavascriptv8.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useCookies

✓ import { useCookies } from 'react-cookie';

✗ const useCookies = require('react-cookie').useCookies;

Primary hook for accessing and modifying cookies. CommonJS `require` is generally discouraged in modern React projects using ESM.

CookiesProvider

✓ import { CookiesProvider } from 'react-cookie';

✗ import CookiesProvider from 'react-cookie';

Provides a cookie context to all children. It's a named export, not a default export.

withCookies

✓ import { withCookies } from 'react-cookie';

✗ 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.

✓ import { Cookies } from 'react-cookie';

✗ import UniversalCookies from 'react-cookie/universal-cookie';

Refers to the underlying `universal-cookie` instance for imperative access outside React components. It's a re-export from `universal-cookie`.

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> ); }

Debug

Known issues

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.

affects: >=3.0.0

gotchaCookies 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.

affects: >=0.0.0

breakingWhen 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}>`.

affects: >=3.0.0

gotchaThe `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'])`.

affects: >=3.0.0

Errors

Common errors & fixes

Error: useCookies must be used within a CookiesProvider

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')

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'.

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.

Upgrade

Version history

8.1.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency, required for React hooks and components.

universal-cookierequiredCore runtime dependency providing the underlying cookie management logic.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ItsBenCodes/cookies ↗

packagehttps://www.npmjs.com/package/react-cookie ↗

homepagehttps://react-cookie.github.io/react-cookie/ ↗