https://github.com/notrab/react-use-cart
React hook library for managing cart state
https://github.com/notrab/react-use-cart
cart cart-items cart-state react-hook-library shopping-cart
Last synced: 29 days ago
JSON representation
React hook library for managing cart state
- Host: GitHub
- URL: https://github.com/notrab/react-use-cart
- Owner: notrab
- License: apache-2.0
- Created: 2019-11-06T10:23:22.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-05-09T04:22:32.000Z (about 1 month ago)
- Last Synced: 2025-05-09T05:25:38.897Z (about 1 month ago)
- Topics: cart, cart-items, cart-state, react-hook-library, shopping-cart
- Language: TypeScript
- Homepage: http://npm.im/react-use-cart
- Size: 902 KB
- Stars: 375
- Watchers: 6
- Forks: 49
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
react-use-cart
🛒 A lightweight shopping cart hook for React, Next.js, and Gatsby
## Why?
- 
- **No dependencies**
- 💳 Not tied to any payment gateway, or checkout - create your own!
- 🔥 Persistent carts with local storage, or your own adapter
- ⭐️ Supports multiples carts per page
- 🛒 Flexible cart item schema
- 🥞 Works with Next, Gatsby, React
- ♻️ Trigger your own side effects with cart handlers (on item add, update, remove)
- 🛠 Built with TypeScript
- ✅ Fully tested
- 🌮 Used by [Dines](https://dines.co.uk/?ref=react-use-cart)
## Quick Start
[Demo](https://codesandbox.io/s/react-use-cart-3c7vm)
```js
import { CartProvider, useCart } from "react-use-cart";
function Page() {
const { addItem } = useCart();
const products = [
{
id: 1,
name: "Malm",
price: 9900,
quantity: 1
},
{
id: 2,
name: "Nordli",
price: 16500,
quantity: 5
},
{
id: 3,
name: "Kullen",
price: 4500,
quantity: 1
},
];
return (
{products.map((p) => (
addItem(p)}>Add to cart
))}
);
}
function Cart() {
const {
isEmpty,
totalUniqueItems,
items,
updateItemQuantity,
removeItem,
} = useCart();
if (isEmpty) return
Your cart is empty
;
return (
<>
Cart ({totalUniqueItems})
-
{item.quantity} x {item.name} —
updateItemQuantity(item.id, (item.quantity ?? 0) - 1)}
>
-
updateItemQuantity(item.id, (item.quantity ?? 0) + 1)}
>
+
removeItem(item.id)}>×
{items.map((item) => (
))}
>
);
}
function App() {
return (
);
}
```
## Install
```bash
npm install react-use-cart # yarn add react-use-cart
```
## `CartProvider`
You will need to wrap your application with the `CartProvider` component so that the `useCart` hook can access the cart state.
Carts are persisted across visits using `localStorage`, unless you specify your own `storage` adapter.
#### Usage
```js
import React from "react";
import ReactDOM from "react-dom";
import { CartProvider } from "react-use-cart";
ReactDOM.render(
{/* render app/cart here */},
document.getElementById("root")
);
```
#### Props
| Prop | Required | Description |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | _No_ | `id` for your cart to enable automatic cart retrieval via `window.localStorage`. If you pass a `id` then you can use multiple instances of `CartProvider`. |
| `onSetItems` | _No_ | Triggered only when `setItems` invoked. |
| `onItemAdd` | _No_ | Triggered on items added to your cart, unless the item already exists, then `onItemUpdate` will be invoked. |
| `onItemUpdate` | _No_ | Triggered on items updated in your cart, unless you are setting the quantity to `0`, then `onItemRemove` will be invoked. |
| `onItemRemove` | _No_ | Triggered on items removed from your cart. |
| `onEmptyCart` | _No_ | Triggered on empty cart. |
| `storage` | _No_ | Must return `[getter, setter]`. |
| `metadata` | _No_ | Custom global state on the cart. Stored inside of `metadata`. |
## `useCart`
The `useCart` hook exposes all the getter/setters for your cart state.
### `setItems(items)`
The `setItems` method should be used to set all items in the cart. This will overwrite any existing cart items. A `quantity` default of 1 will be set for an item implicitly if no `quantity` is specified.
#### Args
- `items[]` (**Required**): An array of cart item object. You must provide an `id` and `price` value for new items that you add to cart.
#### Usage
```js
import { useCart } from "react-use-cart";
const { setItems } = useCart();
const products = [
{
id: "ckb64v21u000001ksgw2s42ku",
name: "Fresh Foam 1080v9",
brand: "New Balance",
color: "Neon Emerald with Dark Neptune",
size: "US 10",
width: "B - Standard",
sku: "W1080LN9",
price: 15000,
},
{
id: "cjld2cjxh0000qzrmn831i7rn",
name: "Fresh Foam 1080v9",
brand: "New Balance",
color: "Neon Emerald with Dark Neptune",
size: "US 9",
width: "B - Standard",
sku: "W1080LN9",
price: 15000,
},
];
setItems(products);
```
### `addItem(item, quantity)`
The `addItem` method should be used to add items to the cart.
#### Args
- `item` (**Required**): An object that represents your cart item. You must provide an `id` and `price` value for new items that you add to cart.
- `quantity` (_optional_, **default**: `1`): The amount of items you want to add.
#### Usage
```js
import { useCart } from "react-use-cart";
const { addItem } = useCart();
const product = {
id: "cjld2cjxh0000qzrmn831i7rn",
name: "Fresh Foam 1080v9",
brand: "New Balance",
color: "Neon Emerald with Dark Neptune",
size: "US 9",
width: "B - Standard",
sku: "W1080LN9",
price: 15000,
};
addItem(product, 2);
```
### `updateItem(itemId, data)`
The `updateItem` method should be used to update items in the cart.
#### Args
- `itemId` (**Required**): The cart item `id` you want to update.
- `data` (**Required**): The updated cart item object.
#### Usage
```js
import { useCart } from "react-use-cart";
const { updateItem } = useCart();
updateItem("cjld2cjxh0000qzrmn831i7rn", {
size: "UK 10",
});
```
### `updateItemQuantity(itemId, quantity)`
The `updateItemQuantity` method should be used to update an items `quantity` value.
#### Args
- `itemId` (**Required**): The cart item `id` you want to update.
- `quantity` (**Required**): The updated cart item quantity.
#### Usage
```js
import { useCart } from "react-use-cart";
const { updateItemQuantity } = useCart();
updateItemQuantity("cjld2cjxh0000qzrmn831i7rn", 1);
```
### `removeItem(itemId)`
The `removeItem` method should be used to remove an item from the cart.
#### Args
- `itemId` (**Required**): The cart item `id` you want to remove.
#### Usage
```js
import { useCart } from "react-use-cart";
const { removeItem } = useCart();
removeItem("cjld2cjxh0000qzrmn831i7rn");
```
### `emptyCart()`
The `emptyCart()` method should be used to remove all cart items, and resetting cart totals to the default `0` values.
#### Usage
```js
import { useCart } from "react-use-cart";
const { emptyCart } = useCart();
emptyCart();
```
### `clearCartMetadata()`
The `clearCartMetadata()` will reset the `metadata` to an empty object.
#### Usage
```js
import { useCart } from "react-use-cart";
const { clearCartMetadata } = useCart();
clearCartMetadata();
```
### `setCartMetadata(object)`
The `setCartMetadata()` will replace the `metadata` object on the cart. You must pass it an object.
#### Args
- `object`: A object with key/value pairs. The key being a string.
#### Usage
```js
import { useCart } from "react-use-cart";
const { setCartMetadata } = useCart();
setCartMetadata({ notes: "This is the only metadata" });
```
### `updateCartMetadata(object)`
The `updateCartMetadata()` will update the `metadata` object on the cart. You must pass it an object. This will merge the passed object with the existing metadata.
#### Args
- `object`: A object with key/value pairs. The key being a string.
#### Usage
```js
import { useCart } from "react-use-cart";
const { updateCartMetadata } = useCart();
updateCartMetadata({ notes: "Leave in shed" });
```
### `items = []`
This will return the current cart items in an array.
#### Usage
```js
import { useCart } from "react-use-cart";
const { items } = useCart();
```
### `isEmpty = false`
A quick and easy way to check if the cart is empty. Returned as a boolean.
#### Usage
```js
import { useCart } from "react-use-cart";
const { isEmpty } = useCart();
```
### `getItem(itemId)`
Get a specific cart item by `id`. Returns the item object.
#### Args
- `itemId` (**Required**): The `id` of the item you're fetching.
#### Usage
```js
import { useCart } from "react-use-cart";
const { getItem } = useCart();
const myItem = getItem("cjld2cjxh0000qzrmn831i7rn");
```
### `inCart(itemId)`
Quickly check if an item is in the cart. Returned as a boolean.
#### Args
- `itemId` (**Required**): The `id` of the item you're looking for.
#### Usage
```js
import { useCart } from "react-use-cart";
const { inCart } = useCart();
inCart("cjld2cjxh0000qzrmn831i7rn") ? "In cart" : "Not in cart";
```
### `totalItems = 0`
This returns the totaly quantity of items in the cart as an integer.
#### Usage
```js
import { useCart } from "react-use-cart";
const { totalItems } = useCart();
```
### `totalUniqueItems = 0`
This returns the total unique items in the cart as an integer.
#### Usage
```js
import { useCart } from "react-use-cart";
const { totalUniqueItems } = useCart();
```
### `cartTotal = 0`
This returns the total value of all items in the cart.
#### Usage
```js
import { useCart } from "react-use-cart";
const { cartTotal } = useCart();
```
### `metadata = {}`
This returns the metadata set with `updateCartMetadata`. This is useful for storing additional cart, or checkout values.
#### Usage
```js
import { useCart } from "react-use-cart";
const { metadata } = useCart();
```
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Tobias Nielsen
💻
Craig Tweedy
💻
Jonathan Steele
💻
Scott Spence
💡
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!