(
65 | initialState
66 | );
67 |
68 | export const createCartIdentifier = (len = 12) =>
69 | [...Array(len)].map(() => (~~(Math.random() * 36)).toString(36)).join("");
70 |
71 | export const useCart = () => {
72 | const context = React.useContext(CartContext);
73 |
74 | if (!context) throw new Error("Expected to be wrapped in a CartProvider");
75 |
76 | return context;
77 | };
78 |
79 | function reducer(state: CartProviderState, action: Actions) {
80 | switch (action.type) {
81 | case "SET_ITEMS":
82 | return generateCartState(state, action.payload);
83 |
84 | case "ADD_ITEM": {
85 | const items = [...state.items, action.payload];
86 |
87 | return generateCartState(state, items);
88 | }
89 |
90 | case "UPDATE_ITEM": {
91 | const items = state.items.map((item: Item) => {
92 | if (item.id !== action.id) return item;
93 |
94 | return {
95 | ...item,
96 | ...action.payload,
97 | };
98 | });
99 |
100 | return generateCartState(state, items);
101 | }
102 |
103 | case "REMOVE_ITEM": {
104 | const items = state.items.filter((i: Item) => i.id !== action.id);
105 |
106 | return generateCartState(state, items);
107 | }
108 |
109 | case "EMPTY_CART":
110 | return initialState;
111 |
112 | case "CLEAR_CART_META":
113 | return {
114 | ...state,
115 | metadata: {},
116 | };
117 |
118 | case "SET_CART_META":
119 | return {
120 | ...state,
121 | metadata: {
122 | ...action.payload,
123 | },
124 | };
125 |
126 | case "UPDATE_CART_META":
127 | return {
128 | ...state,
129 | metadata: {
130 | ...state.metadata,
131 | ...action.payload,
132 | },
133 | };
134 |
135 | default:
136 | throw new Error("No action specified");
137 | }
138 | }
139 |
140 | const generateCartState = (state = initialState, items: Item[]) => {
141 | const totalUniqueItems = calculateUniqueItems(items);
142 | const isEmpty = totalUniqueItems === 0;
143 |
144 | return {
145 | ...initialState,
146 | ...state,
147 | items: calculateItemTotals(items),
148 | totalItems: calculateTotalItems(items),
149 | totalUniqueItems,
150 | cartTotal: calculateTotal(items),
151 | isEmpty,
152 | };
153 | };
154 |
155 | const calculateItemTotals = (items: Item[]) =>
156 | items.map(item => ({
157 | ...item,
158 | itemTotal: item.price * item.quantity!,
159 | }));
160 |
161 | const calculateTotal = (items: Item[]) =>
162 | items.reduce((total, item) => total + item.quantity! * item.price, 0);
163 |
164 | const calculateTotalItems = (items: Item[]) =>
165 | items.reduce((sum, item) => sum + item.quantity!, 0);
166 |
167 | const calculateUniqueItems = (items: Item[]) => items.length;
168 |
169 | export const CartProvider: React.FC<{
170 | children?: React.ReactNode;
171 | id?: string;
172 | defaultItems?: Item[];
173 | onSetItems?: (items: Item[]) => void;
174 | onItemAdd?: (payload: Item) => void;
175 | onItemUpdate?: (payload: object) => void;
176 | onItemRemove?: (id: Item["id"]) => void;
177 | storage?: (
178 | key: string,
179 | initialValue: string
180 | ) => [string, (value: Function | string) => void];
181 | metadata?: Metadata;
182 | }> = ({
183 | children,
184 | id: cartId,
185 | defaultItems = [],
186 | onSetItems,
187 | onItemAdd,
188 | onItemUpdate,
189 | onItemRemove,
190 | storage = useLocalStorage,
191 | metadata,
192 | }) => {
193 | const id = cartId ? cartId : createCartIdentifier();
194 |
195 | const [savedCart, saveCart] = storage(
196 | cartId ? `react-use-cart-${id}` : `react-use-cart`,
197 | JSON.stringify({
198 | id,
199 | ...initialState,
200 | items: defaultItems,
201 | metadata,
202 | })
203 | );
204 |
205 | const [state, dispatch] = React.useReducer(reducer, JSON.parse(savedCart));
206 | React.useEffect(() => {
207 | saveCart(JSON.stringify(state));
208 | }, [state, saveCart]);
209 |
210 | const setItems = (items: Item[]) => {
211 | dispatch({
212 | type: "SET_ITEMS",
213 | payload: items.map(item => ({
214 | ...item,
215 | quantity: item.quantity || 1,
216 | })),
217 | });
218 |
219 | onSetItems && onSetItems(items);
220 | };
221 |
222 | const addItem = (item: Item, quantity = 1) => {
223 | if (!item.id) throw new Error("You must provide an `id` for items");
224 | if (quantity <= 0) return;
225 |
226 | const currentItem = state.items.find((i: Item) => i.id === item.id);
227 |
228 | if (!currentItem && !item.hasOwnProperty("price"))
229 | throw new Error("You must pass a `price` for new items");
230 |
231 | if (!currentItem) {
232 | const payload = { ...item, quantity };
233 |
234 | dispatch({ type: "ADD_ITEM", payload });
235 |
236 | onItemAdd && onItemAdd(payload);
237 |
238 | return;
239 | }
240 |
241 | const payload = { ...item, quantity: currentItem.quantity + quantity };
242 |
243 | dispatch({
244 | type: "UPDATE_ITEM",
245 | id: item.id,
246 | payload,
247 | });
248 |
249 | onItemUpdate && onItemUpdate(payload);
250 | };
251 |
252 | const updateItem = (id: Item["id"], payload: object) => {
253 | if (!id || !payload) {
254 | return;
255 | }
256 |
257 | dispatch({ type: "UPDATE_ITEM", id, payload });
258 |
259 | onItemUpdate && onItemUpdate(payload);
260 | };
261 |
262 | const updateItemQuantity = (id: Item["id"], quantity: number) => {
263 | if (quantity <= 0) {
264 | onItemRemove && onItemRemove(id);
265 |
266 | dispatch({ type: "REMOVE_ITEM", id });
267 |
268 | return;
269 | }
270 |
271 | const currentItem = state.items.find((item: Item) => item.id === id);
272 |
273 | if (!currentItem) throw new Error("No such item to update");
274 |
275 | const payload = { ...currentItem, quantity };
276 |
277 | dispatch({
278 | type: "UPDATE_ITEM",
279 | id,
280 | payload,
281 | });
282 |
283 | onItemUpdate && onItemUpdate(payload);
284 | };
285 |
286 | const removeItem = (id: Item["id"]) => {
287 | if (!id) return;
288 |
289 | dispatch({ type: "REMOVE_ITEM", id });
290 |
291 | onItemRemove && onItemRemove(id);
292 | };
293 |
294 | const emptyCart = () =>
295 | dispatch({
296 | type: "EMPTY_CART",
297 | });
298 |
299 | const getItem = (id: Item["id"]) =>
300 | state.items.find((i: Item) => i.id === id);
301 |
302 | const inCart = (id: Item["id"]) => state.items.some((i: Item) => i.id === id);
303 |
304 | const clearCartMetadata = () => {
305 | dispatch({
306 | type: "CLEAR_CART_META",
307 | });
308 | };
309 |
310 | const setCartMetadata = (metadata: Metadata) => {
311 | if (!metadata) return;
312 |
313 | dispatch({
314 | type: "SET_CART_META",
315 | payload: metadata,
316 | });
317 | };
318 |
319 | const updateCartMetadata = (metadata: Metadata) => {
320 | if (!metadata) return;
321 |
322 | dispatch({
323 | type: "UPDATE_CART_META",
324 | payload: metadata,
325 | });
326 | };
327 |
328 | return (
329 |
345 | {children}
346 |
347 | );
348 | };
349 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Apache License
2 | Version 2.0, January 2004
3 | http://www.apache.org/licenses/
4 |
5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6 |
7 | 1. Definitions.
8 |
9 | "License" shall mean the terms and conditions for use, reproduction,
10 | and distribution as defined by Sections 1 through 9 of this document.
11 |
12 | "Licensor" shall mean the copyright owner or entity authorized by
13 | the copyright owner that is granting the License.
14 |
15 | "Legal Entity" shall mean the union of the acting entity and all
16 | other entities that control, are controlled by, or are under common
17 | control with that entity. For the purposes of this definition,
18 | "control" means (i) the power, direct or indirect, to cause the
19 | direction or management of such entity, whether by contract or
20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
21 | outstanding shares, or (iii) beneficial ownership of such entity.
22 |
23 | "You" (or "Your") shall mean an individual or Legal Entity
24 | exercising permissions granted by this License.
25 |
26 | "Source" form shall mean the preferred form for making modifications,
27 | including but not limited to software source code, documentation
28 | source, and configuration files.
29 |
30 | "Object" form shall mean any form resulting from mechanical
31 | transformation or translation of a Source form, including but
32 | not limited to compiled object code, generated documentation,
33 | and conversions to other media types.
34 |
35 | "Work" shall mean the work of authorship, whether in Source or
36 | Object form, made available under the License, as indicated by a
37 | copyright notice that is included in or attached to the work
38 | (an example is provided in the Appendix below).
39 |
40 | "Derivative Works" shall mean any work, whether in Source or Object
41 | form, that is based on (or derived from) the Work and for which the
42 | editorial revisions, annotations, elaborations, or other modifications
43 | represent, as a whole, an original work of authorship. For the purposes
44 | of this License, Derivative Works shall not include works that remain
45 | separable from, or merely link (or bind by name) to the interfaces of,
46 | the Work and Derivative Works thereof.
47 |
48 | "Contribution" shall mean any work of authorship, including
49 | the original version of the Work and any modifications or additions
50 | to that Work or Derivative Works thereof, that is intentionally
51 | submitted to Licensor for inclusion in the Work by the copyright owner
52 | or by an individual or Legal Entity authorized to submit on behalf of
53 | the copyright owner. For the purposes of this definition, "submitted"
54 | means any form of electronic, verbal, or written communication sent
55 | to the Licensor or its representatives, including but not limited to
56 | communication on electronic mailing lists, source code control systems,
57 | and issue tracking systems that are managed by, or on behalf of, the
58 | Licensor for the purpose of discussing and improving the Work, but
59 | excluding communication that is conspicuously marked or otherwise
60 | designated in writing by the copyright owner as "Not a Contribution."
61 |
62 | "Contributor" shall mean Licensor and any individual or Legal Entity
63 | on behalf of whom a Contribution has been received by Licensor and
64 | subsequently incorporated within the Work.
65 |
66 | 2. Grant of Copyright License. Subject to the terms and conditions of
67 | this License, each Contributor hereby grants to You a perpetual,
68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69 | copyright license to reproduce, prepare Derivative Works of,
70 | publicly display, publicly perform, sublicense, and distribute the
71 | Work and such Derivative Works in Source or Object form.
72 |
73 | 3. Grant of Patent License. Subject to the terms and conditions of
74 | this License, each Contributor hereby grants to You a perpetual,
75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76 | (except as stated in this section) patent license to make, have made,
77 | use, offer to sell, sell, import, and otherwise transfer the Work,
78 | where such license applies only to those patent claims licensable
79 | by such Contributor that are necessarily infringed by their
80 | Contribution(s) alone or by combination of their Contribution(s)
81 | with the Work to which such Contribution(s) was submitted. If You
82 | institute patent litigation against any entity (including a
83 | cross-claim or counterclaim in a lawsuit) alleging that the Work
84 | or a Contribution incorporated within the Work constitutes direct
85 | or contributory patent infringement, then any patent licenses
86 | granted to You under this License for that Work shall terminate
87 | as of the date such litigation is filed.
88 |
89 | 4. Redistribution. You may reproduce and distribute copies of the
90 | Work or Derivative Works thereof in any medium, with or without
91 | modifications, and in Source or Object form, provided that You
92 | meet the following conditions:
93 |
94 | (a) You must give any other recipients of the Work or
95 | Derivative Works a copy of this License; and
96 |
97 | (b) You must cause any modified files to carry prominent notices
98 | stating that You changed the files; and
99 |
100 | (c) You must retain, in the Source form of any Derivative Works
101 | that You distribute, all copyright, patent, trademark, and
102 | attribution notices from the Source form of the Work,
103 | excluding those notices that do not pertain to any part of
104 | the Derivative Works; and
105 |
106 | (d) If the Work includes a "NOTICE" text file as part of its
107 | distribution, then any Derivative Works that You distribute must
108 | include a readable copy of the attribution notices contained
109 | within such NOTICE file, excluding those notices that do not
110 | pertain to any part of the Derivative Works, in at least one
111 | of the following places: within a NOTICE text file distributed
112 | as part of the Derivative Works; within the Source form or
113 | documentation, if provided along with the Derivative Works; or,
114 | within a display generated by the Derivative Works, if and
115 | wherever such third-party notices normally appear. The contents
116 | of the NOTICE file are for informational purposes only and
117 | do not modify the License. You may add Your own attribution
118 | notices within Derivative Works that You distribute, alongside
119 | or as an addendum to the NOTICE text from the Work, provided
120 | that such additional attribution notices cannot be construed
121 | as modifying the License.
122 |
123 | You may add Your own copyright statement to Your modifications and
124 | may provide additional or different license terms and conditions
125 | for use, reproduction, or distribution of Your modifications, or
126 | for any such Derivative Works as a whole, provided Your use,
127 | reproduction, and distribution of the Work otherwise complies with
128 | the conditions stated in this License.
129 |
130 | 5. Submission of Contributions. Unless You explicitly state otherwise,
131 | any Contribution intentionally submitted for inclusion in the Work
132 | by You to the Licensor shall be under the terms and conditions of
133 | this License, without any additional terms or conditions.
134 | Notwithstanding the above, nothing herein shall supersede or modify
135 | the terms of any separate license agreement you may have executed
136 | with Licensor regarding such Contributions.
137 |
138 | 6. Trademarks. This License does not grant permission to use the trade
139 | names, trademarks, service marks, or product names of the Licensor,
140 | except as required for reasonable and customary use in describing the
141 | origin of the Work and reproducing the content of the NOTICE file.
142 |
143 | 7. Disclaimer of Warranty. Unless required by applicable law or
144 | agreed to in writing, Licensor provides the Work (and each
145 | Contributor provides its Contributions) on an "AS IS" BASIS,
146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 | implied, including, without limitation, any warranties or conditions
148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 | PARTICULAR PURPOSE. You are solely responsible for determining the
150 | appropriateness of using or redistributing the Work and assume any
151 | risks associated with Your exercise of permissions under this License.
152 |
153 | 8. Limitation of Liability. In no event and under no legal theory,
154 | whether in tort (including negligence), contract, or otherwise,
155 | unless required by applicable law (such as deliberate and grossly
156 | negligent acts) or agreed to in writing, shall any Contributor be
157 | liable to You for damages, including any direct, indirect, special,
158 | incidental, or consequential damages of any character arising as a
159 | result of this License or out of the use or inability to use the
160 | Work (including but not limited to damages for loss of goodwill,
161 | work stoppage, computer failure or malfunction, or any and all
162 | other commercial damages or losses), even if such Contributor
163 | has been advised of the possibility of such damages.
164 |
165 | 9. Accepting Warranty or Additional Liability. While redistributing
166 | the Work or Derivative Works thereof, You may choose to offer,
167 | and charge a fee for, acceptance of support, warranty, indemnity,
168 | or other liability obligations and/or rights consistent with this
169 | License. However, in accepting such obligations, You may act only
170 | on Your own behalf and on Your sole responsibility, not on behalf
171 | of any other Contributor, and only if You agree to indemnify,
172 | defend, and hold each Contributor harmless for any liability
173 | incurred by, or claims asserted against, such Contributor by reason
174 | of your accepting any such warranty or additional liability.
175 |
176 | END OF TERMS AND CONDITIONS
177 |
178 | APPENDIX: How to apply the Apache License to your work.
179 |
180 | To apply the Apache License to your work, attach the following
181 | boilerplate notice, with the fields enclosed by brackets "[]"
182 | replaced with your own identifying information. (Don't include
183 | the brackets!) The text should be enclosed in the appropriate
184 | comment syntax for the file format. We also recommend that a
185 | file or class name and description of purpose be included on the
186 | same "printed page" as the copyright notice for easier
187 | identification within third-party archives.
188 |
189 | Copyright [yyyy] [name of copyright owner]
190 |
191 | Licensed under the Apache License, Version 2.0 (the "License");
192 | you may not use this file except in compliance with the License.
193 | You may obtain a copy of the License at
194 |
195 | http://www.apache.org/licenses/LICENSE-2.0
196 |
197 | Unless required by applicable law or agreed to in writing, software
198 | distributed under the License is distributed on an "AS IS" BASIS,
199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200 | See the License for the specific language governing permissions and
201 | limitations under the License.
202 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 | react-use-cart
3 |
4 |
5 | 🛒 A lightweight shopping cart hook for React, Next.js, and Gatsby
6 |
7 |
8 |
9 |
10 | 
11 |
12 |
13 | 
14 |
15 |
16 | 
17 |
18 |
19 | 
20 |
21 |
22 | 
23 |
24 | 
25 |
26 | 
27 |
28 |
29 |
30 | ## Why?
31 |
32 | - 
33 | - **No dependencies**
34 | - 💳 Not tied to any payment gateway, or checkout - create your own!
35 | - 🔥 Persistent carts with local storage, or your own adapter
36 | - ⭐️ Supports multiples carts per page
37 | - 🛒 Flexible cart item schema
38 | - 🥞 Works with Next, Gatsby, React
39 | - ♻️ Trigger your own side effects with cart handlers (on item add, update, remove)
40 | - 🛠 Built with TypeScript
41 | - ✅ Fully tested
42 | - 🌮 Used by [Dines](https://dines.co.uk/?ref=react-use-cart)
43 |
44 | ## Quick Start
45 |
46 | [Demo](https://codesandbox.io/s/react-use-cart-3c7vm)
47 |
48 | ```js
49 | import { CartProvider, useCart } from "react-use-cart";
50 |
51 | function Page() {
52 | const { addItem } = useCart();
53 |
54 | const products = [
55 | {
56 | id: 1,
57 | name: "Malm",
58 | price: 9900,
59 | quantity: 1
60 | },
61 | {
62 | id: 2,
63 | name: "Nordli",
64 | price: 16500,
65 | quantity: 5
66 | },
67 | {
68 | id: 3,
69 | name: "Kullen",
70 | price: 4500,
71 | quantity: 1
72 | },
73 | ];
74 |
75 | return (
76 |
77 | {products.map((p) => (
78 |
79 |
80 |
81 | ))}
82 |
Your cart is empty
;
96 |
97 | return (
98 | <>
99 | Cart ({totalUniqueItems})
100 |
101 |
102 | {items.map((item) => (
103 | -
104 | {item.quantity} x {item.name} —
105 |
110 |
115 |
116 |
117 | ))}
118 |
119 |
120 | );
121 | }
122 |
123 | function App() {
124 | return (
125 |
126 |
127 |
128 |
129 | );
130 | }
131 | ```
132 |
133 | ## Install
134 |
135 | ```bash
136 | npm install react-use-cart # yarn add react-use-cart
137 | ```
138 |
139 | ## `CartProvider`
140 |
141 | You will need to wrap your application with the `CartProvider` component so that the `useCart` hook can access the cart state.
142 |
143 | Carts are persisted across visits using `localStorage`, unless you specify your own `storage` adapter.
144 |
145 | #### Usage
146 |
147 | ```js
148 | import React from "react";
149 | import ReactDOM from "react-dom";
150 | import { CartProvider } from "react-use-cart";
151 |
152 | ReactDOM.render(
153 | {/* render app/cart here */},
154 | document.getElementById("root")
155 | );
156 | ```
157 |
158 | #### Props
159 |
160 | | Prop | Required | Description |
161 | | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
162 | | `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`. |
163 | | `onSetItems` | _No_ | Triggered only when `setItems` invoked. |
164 | | `onItemAdd` | _No_ | Triggered on items added to your cart, unless the item already exists, then `onItemUpdate` will be invoked. |
165 | | `onItemUpdate` | _No_ | Triggered on items updated in your cart, unless you are setting the quantity to `0`, then `onItemRemove` will be invoked. |
166 | | `onItemRemove` | _No_ | Triggered on items removed from your cart. |
167 | | `storage` | _No_ | Must return `[getter, setter]`. |
168 | | `metadata` | _No_ | Custom global state on the cart. Stored inside of `metadata`. |
169 | ## `useCart`
170 |
171 | The `useCart` hook exposes all the getter/setters for your cart state.
172 |
173 | ### `setItems(items)`
174 |
175 | 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.
176 |
177 |
178 | #### Args
179 |
180 | - `items[]` (**Required**): An array of cart item object. You must provide an `id` and `price` value for new items that you add to cart.
181 |
182 | #### Usage
183 |
184 | ```js
185 | import { useCart } from "react-use-cart";
186 |
187 | const { setItems } = useCart();
188 |
189 | const products = [
190 | {
191 | id: "ckb64v21u000001ksgw2s42ku",
192 | name: "Fresh Foam 1080v9",
193 | brand: "New Balance",
194 | color: "Neon Emerald with Dark Neptune",
195 | size: "US 10",
196 | width: "B - Standard",
197 | sku: "W1080LN9",
198 | price: 15000,
199 | },
200 | {
201 | id: "cjld2cjxh0000qzrmn831i7rn",
202 | name: "Fresh Foam 1080v9",
203 | brand: "New Balance",
204 | color: "Neon Emerald with Dark Neptune",
205 | size: "US 9",
206 | width: "B - Standard",
207 | sku: "W1080LN9",
208 | price: 15000,
209 | },
210 | ];
211 |
212 | setItems(products);
213 | ```
214 |
215 | ### `addItem(item, quantity)`
216 |
217 | The `addItem` method should be used to add items to the cart.
218 |
219 | #### Args
220 |
221 | - `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.
222 | - `quantity` (_optional_, **default**: `1`): The amount of items you want to add.
223 |
224 | #### Usage
225 |
226 | ```js
227 | import { useCart } from "react-use-cart";
228 |
229 | const { addItem } = useCart();
230 |
231 | const product = {
232 | id: "cjld2cjxh0000qzrmn831i7rn",
233 | name: "Fresh Foam 1080v9",
234 | brand: "New Balance",
235 | color: "Neon Emerald with Dark Neptune",
236 | size: "US 9",
237 | width: "B - Standard",
238 | sku: "W1080LN9",
239 | price: 15000,
240 | };
241 |
242 | addItem(product, 2);
243 | ```
244 |
245 | ### `updateItem(itemId, data)`
246 |
247 | The `updateItem` method should be used to update items in the cart.
248 |
249 | #### Args
250 |
251 | - `itemId` (**Required**): The cart item `id` you want to update.
252 | - `data` (**Required**): The updated cart item object.
253 |
254 | #### Usage
255 |
256 | ```js
257 | import { useCart } from "react-use-cart";
258 |
259 | const { updateItem } = useCart();
260 |
261 | updateItem("cjld2cjxh0000qzrmn831i7rn", {
262 | size: "UK 10",
263 | });
264 | ```
265 |
266 | ### `updateItemQuantity(itemId, quantity)`
267 |
268 | The `updateItemQuantity` method should be used to update an items `quantity` value.
269 |
270 | #### Args
271 |
272 | - `itemId` (**Required**): The cart item `id` you want to update.
273 | - `quantity` (**Required**): The updated cart item quantity.
274 |
275 | #### Usage
276 |
277 | ```js
278 | import { useCart } from "react-use-cart";
279 |
280 | const { updateItemQuantity } = useCart();
281 |
282 | updateItemQuantity("cjld2cjxh0000qzrmn831i7rn", 1);
283 | ```
284 |
285 | ### `removeItem(itemId)`
286 |
287 | The `removeItem` method should be used to remove an item from the cart.
288 |
289 | #### Args
290 |
291 | - `itemId` (**Required**): The cart item `id` you want to remove.
292 |
293 | #### Usage
294 |
295 | ```js
296 | import { useCart } from "react-use-cart";
297 |
298 | const { removeItem } = useCart();
299 |
300 | removeItem("cjld2cjxh0000qzrmn831i7rn");
301 | ```
302 |
303 | ### `emptyCart()`
304 |
305 | The `emptyCart()` method should be used to remove all cart items, and resetting cart totals to the default `0` values.
306 |
307 | #### Usage
308 |
309 | ```js
310 | import { useCart } from "react-use-cart";
311 |
312 | const { emptyCart } = useCart();
313 |
314 | emptyCart();
315 | ```
316 |
317 | ### `clearCartMetadata()`
318 |
319 | The `clearCartMetadata()` will reset the `metadata` to an empty object.
320 |
321 | #### Usage
322 |
323 | ```js
324 | import { useCart } from "react-use-cart";
325 |
326 | const { clearCartMetadata } = useCart();
327 |
328 | clearCartMetadata();
329 | ```
330 |
331 | ### `setCartMetadata(object)`
332 |
333 | The `setCartMetadata()` will replace the `metadata` object on the cart. You must pass it an object.
334 |
335 | #### Args
336 |
337 | - `object`: A object with key/value pairs. The key being a string.
338 |
339 | #### Usage
340 |
341 | ```js
342 | import { useCart } from "react-use-cart";
343 |
344 | const { setCartMetadata } = useCart();
345 |
346 | setCartMetadata({ notes: "This is the only metadata" });
347 | ```
348 |
349 | ### `updateCartMetadata(object)`
350 |
351 | 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.
352 |
353 | #### Args
354 |
355 | - `object`: A object with key/value pairs. The key being a string.
356 |
357 | #### Usage
358 |
359 | ```js
360 | import { useCart } from "react-use-cart";
361 |
362 | const { updateCartMetadata } = useCart();
363 |
364 | updateCartMetadata({ notes: "Leave in shed" });
365 | ```
366 |
367 | ### `items = []`
368 |
369 | This will return the current cart items in an array.
370 |
371 | #### Usage
372 |
373 | ```js
374 | import { useCart } from "react-use-cart";
375 |
376 | const { items } = useCart();
377 | ```
378 |
379 | ### `isEmpty = false`
380 |
381 | A quick and easy way to check if the cart is empty. Returned as a boolean.
382 |
383 | #### Usage
384 |
385 | ```js
386 | import { useCart } from "react-use-cart";
387 |
388 | const { isEmpty } = useCart();
389 | ```
390 |
391 | ### `getItem(itemId)`
392 |
393 | Get a specific cart item by `id`. Returns the item object.
394 |
395 | #### Args
396 |
397 | - `itemId` (**Required**): The `id` of the item you're fetching.
398 |
399 | #### Usage
400 |
401 | ```js
402 | import { useCart } from "react-use-cart";
403 |
404 | const { getItem } = useCart();
405 |
406 | const myItem = getItem("cjld2cjxh0000qzrmn831i7rn");
407 | ```
408 |
409 | ### `inCart(itemId)`
410 |
411 | Quickly check if an item is in the cart. Returned as a boolean.
412 |
413 | #### Args
414 |
415 | - `itemId` (**Required**): The `id` of the item you're looking for.
416 |
417 | #### Usage
418 |
419 | ```js
420 | import { useCart } from "react-use-cart";
421 |
422 | const { inCart } = useCart();
423 |
424 | inCart("cjld2cjxh0000qzrmn831i7rn") ? "In cart" : "Not in cart";
425 | ```
426 |
427 | ### `totalItems = 0`
428 |
429 | This returns the totaly quantity of items in the cart as an integer.
430 |
431 | #### Usage
432 |
433 | ```js
434 | import { useCart } from "react-use-cart";
435 |
436 | const { totalItems } = useCart();
437 | ```
438 |
439 | ### `totalUniqueItems = 0`
440 |
441 | This returns the total unique items in the cart as an integer.
442 |
443 | #### Usage
444 |
445 | ```js
446 | import { useCart } from "react-use-cart";
447 |
448 | const { totalUniqueItems } = useCart();
449 | ```
450 |
451 | ### `cartTotal = 0`
452 |
453 | This returns the total value of all items in the cart.
454 |
455 | #### Usage
456 |
457 | ```js
458 | import { useCart } from "react-use-cart";
459 |
460 | const { cartTotal } = useCart();
461 | ```
462 |
463 | ### `metadata = {}`
464 |
465 | This returns the metadata set with `updateCartMetadata`. This is useful for storing additional cart, or checkout values.
466 |
467 | #### Usage
468 |
469 | ```js
470 | import { useCart } from "react-use-cart";
471 |
472 | const { metadata } = useCart();
473 | ```
474 |
475 | ## Contributors ✨
476 |
477 | Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
478 |
479 |
480 |
481 |
482 |
490 |
491 |
492 |
493 |
494 |
495 |
496 | This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
497 |
--------------------------------------------------------------------------------
/test/index.test.tsx:
--------------------------------------------------------------------------------
1 | import {
2 | CartProvider,
3 | createCartIdentifier,
4 | initialState,
5 | useCart,
6 | } from "../src";
7 | import React, { FC, HTMLAttributes, ReactChild } from "react";
8 | import { act, renderHook } from "@testing-library/react-hooks";
9 |
10 | export interface Props extends HTMLAttributes {
11 | children?: ReactChild;
12 | }
13 |
14 | afterEach(() => window.localStorage.clear());
15 |
16 | describe("createCartIdentifier", () => {
17 | test("returns a 12 character string by default", () => {
18 | const id = createCartIdentifier();
19 |
20 | expect(id).toHaveLength(12);
21 | });
22 |
23 | test("returns a custom length string", () => {
24 | const id = createCartIdentifier(20);
25 |
26 | expect(id).toHaveLength(20);
27 | });
28 |
29 | test("created id is unique", () => {
30 | const id = createCartIdentifier();
31 | const id2 = createCartIdentifier();
32 |
33 | expect(id).not.toEqual(id2);
34 | });
35 | });
36 |
37 | describe("CartProvider", () => {
38 | test("uses ID for cart if provided", () => {
39 | const wrapper: FC = ({ children }) => (
40 | {children}
41 | );
42 |
43 | const { result } = renderHook(() => useCart(), {
44 | wrapper,
45 | });
46 |
47 | expect(result.current.id).toBeDefined();
48 | expect(result.current.id).toEqual("test");
49 | });
50 |
51 | test("creates an ID for cart if non provided", () => {
52 | const { result } = renderHook(() => useCart(), {
53 | wrapper: CartProvider,
54 | });
55 |
56 | expect(result.current.id).toBeDefined();
57 | expect(result.current.id).toHaveLength(12);
58 | });
59 |
60 | test("initial cart meta state is set", () => {
61 | const { result } = renderHook(() => useCart(), {
62 | wrapper: CartProvider,
63 | });
64 |
65 | expect(result.current.items).toEqual(initialState.items);
66 | expect(result.current.totalItems).toEqual(initialState.totalItems);
67 | expect(result.current.totalUniqueItems).toEqual(
68 | initialState.totalUniqueItems
69 | );
70 | expect(result.current.isEmpty).toBe(initialState.isEmpty);
71 | expect(result.current.cartTotal).toEqual(initialState.cartTotal);
72 | });
73 |
74 | test("sets cart metadata", () => {
75 | const metadata = {
76 | coupon: "abc123",
77 | notes: "Leave on door step",
78 | };
79 |
80 | const wrapper: FC = ({ children }) => (
81 | {children}
82 | );
83 |
84 | const { result } = renderHook(() => useCart(), {
85 | wrapper,
86 | });
87 |
88 | expect(result.current.metadata).toEqual(metadata);
89 | });
90 | });
91 |
92 | describe("addItem", () => {
93 | test("adds item to the cart", () => {
94 | const { result } = renderHook(() => useCart(), {
95 | wrapper: CartProvider,
96 | });
97 |
98 | const item = { id: "test", price: 1000 };
99 |
100 | act(() => result.current.addItem(item));
101 |
102 | expect(result.current.items).toHaveLength(1);
103 | expect(result.current.totalItems).toBe(1);
104 | expect(result.current.totalUniqueItems).toBe(1);
105 | });
106 |
107 | test("increments existing item quantity in the cart", () => {
108 | const { result } = renderHook(() => useCart(), {
109 | wrapper: CartProvider,
110 | });
111 |
112 | const item = { id: "test", price: 1000 };
113 | const item2 = { id: "test", price: 1000 };
114 |
115 | act(() => result.current.addItem(item));
116 | act(() => result.current.addItem(item2));
117 |
118 | expect(result.current.items).toHaveLength(1);
119 | expect(result.current.totalItems).toBe(2);
120 | expect(result.current.totalUniqueItems).toBe(1);
121 | });
122 |
123 | test("updates cart meta state", () => {
124 | const { result } = renderHook(() => useCart(), {
125 | wrapper: CartProvider,
126 | });
127 |
128 | const item = { id: "test", price: 1000 };
129 |
130 | act(() => result.current.addItem(item));
131 |
132 | expect(result.current.items).toHaveLength(1);
133 | expect(result.current.totalItems).toBe(1);
134 | expect(result.current.totalUniqueItems).toBe(1);
135 | expect(result.current.cartTotal).toBe(1000);
136 | expect(result.current.isEmpty).toBe(false);
137 | });
138 |
139 | test("allows free item", () => {
140 | const { result } = renderHook(() => useCart(), {
141 | wrapper: CartProvider,
142 | });
143 |
144 | const item = { id: "test", price: 0 };
145 |
146 | act(() => result.current.addItem(item));
147 |
148 | expect(result.current.items).toHaveLength(1);
149 | expect(result.current.totalItems).toBe(1);
150 | expect(result.current.totalUniqueItems).toBe(1);
151 | expect(result.current.cartTotal).toBe(0);
152 | expect(result.current.isEmpty).toBe(false);
153 | });
154 |
155 | test("triggers onItemAdd when cart empty", () => {
156 | let called = false;
157 |
158 | const wrapper: FC = ({ children }) => (
159 | (called = true)}>{children}
160 | );
161 |
162 | const { result } = renderHook(() => useCart(), {
163 | wrapper,
164 | });
165 |
166 | const item = { id: "test", price: 1000 };
167 |
168 | act(() => result.current.addItem(item));
169 |
170 | expect(called).toBe(true);
171 | });
172 |
173 | test("triggers onItemUpdate when cart has existing item", () => {
174 | let called = false;
175 |
176 | const item = { id: "test", price: 1000 };
177 |
178 | const wrapper: FC = ({ children }) => (
179 | (called = true)}>
180 | {children}
181 |
182 | );
183 |
184 | const { result } = renderHook(() => useCart(), {
185 | wrapper,
186 | });
187 |
188 | act(() => result.current.updateItem(item.id, { price: item.price }));
189 |
190 | expect(called).toBe(true);
191 | });
192 |
193 | test("add item with price", () => {
194 | const { result } = renderHook(() => useCart(), {
195 | wrapper: CartProvider,
196 | });
197 |
198 | const item = { id: "test", price: 1000 };
199 |
200 | act(() => result.current.addItem(item));
201 |
202 | expect(result.current.cartTotal).toBe(1000);
203 | });
204 | });
205 |
206 | describe("updateItem", () => {
207 | test("updates cart meta state", () => {
208 | const items = [{ id: "test", price: 1000 }];
209 | const [item] = items;
210 |
211 | const wrapper: FC = ({ children }) => (
212 | {children}
213 | );
214 |
215 | const { result } = renderHook(() => useCart(), {
216 | wrapper,
217 | });
218 |
219 | act(() =>
220 | result.current.updateItem(item.id, {
221 | quantity: 2,
222 | })
223 | );
224 |
225 | expect(result.current.items).toHaveLength(1);
226 | expect(result.current.totalItems).toBe(2);
227 | expect(result.current.totalUniqueItems).toBe(1);
228 | expect(result.current.isEmpty).toBe(false);
229 | });
230 |
231 | test("triggers onItemUpdate when updating existing item", () => {
232 | let called = false;
233 |
234 | const item = { id: "test", price: 1000 };
235 |
236 | const wrapper: FC = ({ children }) => (
237 | (called = true)}>
238 | {children}
239 |
240 | );
241 |
242 | const { result } = renderHook(() => useCart(), {
243 | wrapper,
244 | });
245 |
246 | act(() => result.current.addItem(item));
247 |
248 | expect(called).toBe(true);
249 | });
250 | });
251 |
252 | describe("updateItemQuantity", () => {
253 | test("updates cart meta state", () => {
254 | const items = [{ id: "test", price: 1000 }];
255 | const [item] = items;
256 |
257 | const wrapper: FC = ({ children }) => (
258 | {children}
259 | );
260 |
261 | const { result } = renderHook(() => useCart(), {
262 | wrapper,
263 | });
264 |
265 | act(() => result.current.updateItemQuantity(item.id, 3));
266 |
267 | expect(result.current.items).toHaveLength(1);
268 | expect(result.current.totalItems).toBe(3);
269 | expect(result.current.totalUniqueItems).toBe(1);
270 | expect(result.current.isEmpty).toBe(false);
271 | });
272 |
273 | test("triggers onItemUpdate when setting quantity above 0", () => {
274 | let called = false;
275 |
276 | const item = { id: "test", price: 1000 };
277 |
278 | const wrapper: FC = ({ children }) => (
279 | (called = true)}>
280 | {children}
281 |
282 | );
283 |
284 | const { result } = renderHook(() => useCart(), {
285 | wrapper,
286 | });
287 |
288 | act(() => result.current.updateItemQuantity(item.id, 2));
289 |
290 | expect(result.current.items).toHaveLength(1);
291 | expect(called).toBe(true);
292 | });
293 |
294 | test("triggers onItemRemove when setting quantity to 0", () => {
295 | let called = false;
296 |
297 | const item = { id: "test", price: 1000 };
298 |
299 | const wrapper: FC = ({ children }) => (
300 | (called = true)}>
301 | {children}
302 |
303 | );
304 |
305 | const { result } = renderHook(() => useCart(), {
306 | wrapper,
307 | });
308 |
309 | act(() => result.current.updateItemQuantity(item.id, 0));
310 |
311 | expect(result.current.items).toHaveLength(0);
312 | expect(called).toBe(true);
313 | });
314 |
315 | test("recalculates itemTotal when incrementing item quantity", () => {
316 | const item = { id: "test", price: 1000 };
317 |
318 | const { result } = renderHook(() => useCart(), {
319 | wrapper: CartProvider,
320 | });
321 |
322 | act(() => result.current.addItem(item));
323 | act(() => result.current.updateItemQuantity(item.id, 2));
324 |
325 | expect(result.current.items).toHaveLength(1);
326 | expect(result.current.items).toContainEqual(
327 | expect.objectContaining({ itemTotal: 2000, quantity: 2 })
328 | );
329 | });
330 |
331 | test("recalculates itemTotal when decrementing item quantity", () => {
332 | const item = { id: "test", price: 1000, quantity: 2 };
333 |
334 | const { result } = renderHook(() => useCart(), {
335 | wrapper: CartProvider,
336 | });
337 |
338 | act(() => result.current.addItem(item));
339 | act(() => result.current.updateItemQuantity(item.id, 1));
340 |
341 | expect(result.current.items).toHaveLength(1);
342 | expect(result.current.items).toContainEqual(
343 | expect.objectContaining({ itemTotal: 1000, quantity: 1 })
344 | );
345 | });
346 | });
347 |
348 | describe("removeItem", () => {
349 | test("updates cart meta state", () => {
350 | const items = [{ id: "test", price: 1000 }];
351 | const [item] = items;
352 |
353 | const wrapper: FC = ({ children }) => (
354 | {children}
355 | );
356 |
357 | const { result } = renderHook(() => useCart(), {
358 | wrapper,
359 | });
360 |
361 | act(() => result.current.removeItem(item.id));
362 |
363 | expect(result.current.items).toEqual([]);
364 | expect(result.current.totalItems).toBe(0);
365 | expect(result.current.totalUniqueItems).toBe(0);
366 | expect(result.current.isEmpty).toBe(true);
367 | });
368 |
369 | test("triggers onItemRemove when removing item", () => {
370 | let called = false;
371 |
372 | const item = { id: "test", price: 1000 };
373 |
374 | const wrapper: FC = ({ children }) => (
375 | (called = true)}>
376 | {children}
377 |
378 | );
379 |
380 | const { result } = renderHook(() => useCart(), {
381 | wrapper,
382 | });
383 |
384 | act(() => result.current.updateItemQuantity(item.id, 0));
385 |
386 | expect(called).toBe(true);
387 | });
388 | });
389 |
390 | describe("emptyCart", () => {
391 | test("updates cart meta state", () => {
392 | const items = [{ id: "test", price: 1000 }];
393 |
394 | const wrapper: FC = ({ children }) => (
395 | {children}
396 | );
397 |
398 | const { result } = renderHook(() => useCart(), {
399 | wrapper,
400 | });
401 |
402 | act(() => result.current.emptyCart());
403 |
404 | expect(result.current.items).toEqual([]);
405 | expect(result.current.totalItems).toBe(0);
406 | expect(result.current.totalUniqueItems).toBe(0);
407 | expect(result.current.isEmpty).toBe(true);
408 | });
409 | });
410 |
411 | describe("updateCartMetadata", () => {
412 | test("clears cart metadata", () => {
413 | const { result } = renderHook(() => useCart(), {
414 | wrapper: CartProvider,
415 | });
416 |
417 | const metadata = {
418 | coupon: "abc123",
419 | notes: "Leave on door step",
420 | };
421 |
422 | act(() => result.current.updateCartMetadata(metadata));
423 |
424 | expect(result.current.metadata).toEqual(metadata);
425 |
426 | act(() => result.current.clearCartMetadata());
427 |
428 | expect(result.current.metadata).toEqual({});
429 | });
430 |
431 | test("sets cart metadata", () => {
432 | const { result } = renderHook(() => useCart(), {
433 | wrapper: CartProvider,
434 | });
435 |
436 | const metadata = {
437 | coupon: "abc123",
438 | notes: "Leave on door step",
439 | };
440 |
441 | act(() => result.current.updateCartMetadata(metadata));
442 |
443 | expect(result.current.metadata).toEqual(metadata);
444 |
445 | const replaceMetadata = {
446 | delivery: "same-day",
447 | };
448 |
449 | act(() => result.current.setCartMetadata(replaceMetadata));
450 |
451 | expect(result.current.metadata).toEqual(replaceMetadata);
452 | });
453 |
454 | test("updates cart metadata", () => {
455 | const { result } = renderHook(() => useCart(), {
456 | wrapper: CartProvider,
457 | });
458 |
459 | const metadata = {
460 | coupon: "abc123",
461 | notes: "Leave on door step",
462 | };
463 |
464 | act(() => result.current.updateCartMetadata(metadata));
465 |
466 | expect(result.current.metadata).toEqual(metadata);
467 | });
468 |
469 | test("merge new metadata with existing", () => {
470 | const initialMetadata = {
471 | coupon: "abc123",
472 | };
473 |
474 | const wrapper: FC = ({ children }) => (
475 | {children}
476 | );
477 |
478 | const { result } = renderHook(() => useCart(), {
479 | wrapper,
480 | });
481 |
482 | const metadata = {
483 | notes: "Leave on door step",
484 | };
485 |
486 | act(() => result.current.updateCartMetadata(metadata));
487 |
488 | expect(result.current.metadata).toEqual({
489 | ...initialMetadata,
490 | ...metadata,
491 | });
492 | });
493 | });
494 | describe("setItems", () => {
495 | test("set cart items state", () => {
496 | const items = [
497 | { id: "test", price: 1000 },
498 | { id: "test2", price: 2000 },
499 | ];
500 |
501 | const wrapper: FC = ({ children }) => (
502 | {children}
503 | );
504 | const { result } = renderHook(() => useCart(), {
505 | wrapper,
506 | });
507 |
508 | act(() => result.current.setItems(items));
509 | expect(result.current.items).toHaveLength(2);
510 | expect(result.current.totalItems).toBe(2);
511 | expect(result.current.totalUniqueItems).toBe(2);
512 | expect(result.current.isEmpty).toBe(false);
513 | expect(result.current.items).toContainEqual(
514 | expect.objectContaining({ id: "test2", price: 2000, quantity: 1 })
515 | );
516 | });
517 | test("add custom quantities with setItems", () => {
518 | const items = [
519 | { id: "test", price: 1000, quantity: 2 },
520 | { id: "test2", price: 2000, quantity: 1 },
521 | ];
522 | const wrapper: FC = ({ children }) => (
523 | {children}
524 | );
525 | const { result } = renderHook(() => useCart(), {
526 | wrapper,
527 | });
528 |
529 | act(() => result.current.setItems(items));
530 | expect(result.current.items).toHaveLength(2);
531 | expect(result.current.totalItems).toBe(3);
532 | expect(result.current.totalUniqueItems).toBe(2);
533 | });
534 | test("current items is replaced when setItems has been called with a new set of items", () => {
535 | const itemToBeReplaced = { id: "test", price: 1000 };
536 | const wrapper: FC = ({ children }) => (
537 | {children}
538 | );
539 | const { result } = renderHook(() => useCart(), {
540 | wrapper,
541 | });
542 | const items = [
543 | { id: "test2", price: 2000 },
544 | { id: "test3", price: 3000 },
545 | ];
546 | act(() => result.current.setItems(items));
547 | expect(result.current.items).toHaveLength(2);
548 | expect(result.current.items).not.toContainEqual(
549 | expect.objectContaining(itemToBeReplaced)
550 | );
551 | });
552 | test("trigger onSetItems when setItems is called", () => {
553 | let called = false;
554 |
555 | const wrapper: FC = ({ children }) => (
556 | (called = true)}>{children}
557 | );
558 |
559 | const { result } = renderHook(() => useCart(), {
560 | wrapper,
561 | });
562 |
563 | const items = [{ id: "test", price: 1000 }];
564 |
565 | act(() => result.current.setItems(items));
566 |
567 | expect(called).toBe(true);
568 | });
569 | });
570 |
--------------------------------------------------------------------------------
",
7 | "commit": false,
8 | "contributors": [
9 | {
10 | "login": "getTobiasNielsen",
11 | "name": "Tobias Nielsen",
12 | "avatar_url": "https://avatars.githubusercontent.com/u/54803528?v=4",
13 | "profile": "https://github.com/getTobiasNielsen",
14 | "contributions": [
15 | "code",
16 | "ideas"
17 | ]
18 | },
19 | {
20 | "login": "ynnoj",
21 | "name": "Jonathan Steele",
22 | "avatar_url": "https://avatars.githubusercontent.com/u/3578709?v=4",
23 | "profile": "http://jonathan.steele.pro",
24 | "contributions": [
25 | "code",
26 | "ideas",
27 | "bug"
28 | ]
29 | },
30 | {
31 | "login": "craigtweedy",
32 | "name": "Craig Tweedy",
33 | "avatar_url": "https://avatars.githubusercontent.com/u/612558?v=4",
34 | "profile": "https://github.com/craigtweedy",
35 | "contributions": [
36 | "code",
37 | "ideas",
38 | "bug"
39 | ]
40 | },
41 | {
42 | "login": "spences10",
43 | "name": "Scott Spence",
44 | "avatar_url": "https://avatars.githubusercontent.com/u/234708?v=4",
45 | "profile": "https://scottspence.com",
46 | "contributions": [
47 | "example"
48 | ]
49 | }
50 | ],
51 | "contributorsPerLine": 7,
52 | "projectName": "react-use-cart",
53 | "projectOwner": "notrab",
54 | "repoType": "github",
55 | "repoHost": "https://github.com",
56 | "skipCi": true
57 | }
58 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "react-use-cart",
3 | "version": "0.0.0-semantic-release",
4 | "description": "React hook library for managing cart state.",
5 | "author": "Jamie Barton 
