An open API service indexing awesome lists of open source software.

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

Awesome Lists containing this project

README

        


react-use-cart



🛒 A lightweight shopping cart hook for React, Next.js, and Gatsby



Version


Downloads/week


License


Forks on GitHub


Forks on GitHub

minified + gzip size

Contributors

## Why?

- ![Bundle size](https://badgen.net/bundlephobia/minzip/react-use-cart)
- **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})


    {items.map((item) => (

  • {item.quantity} x {item.name} —
    updateItemQuantity(item.id, (item.quantity ?? 0) - 1)}
    >
    -

    updateItemQuantity(item.id, (item.quantity ?? 0) + 1)}
    >
    +

    removeItem(item.id)}>×

  • ))}

>
);
}

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!