--- title: useCart description: Provides access to the cart object. api_version: 2025-04 api_name: hydrogen-react source_url: html: https://shopify.dev/docs/api/hydrogen-react/latest/hooks/usecart md: https://shopify.dev/docs/api/hydrogen-react/latest/hooks/usecart.md --- # use​Carthook Provides access to the cart object. ## Props() `useCart` hook must be a descendent of a `CartProvider` component. ### Returns * CartWithActionsDocs ### CartWithActionsDocs * attributes Attribute\[] The cart's attributes. * buyerIdentityUpdate (buyerIdenity: CartBuyerIdentityInput) => void A callback that updates the buyer identity in the cart. Expects the same `buyerIdentity` input that you would provide to the Storefront API's `cartBuyerIdentityUpdate` mutation. * cartAttributesUpdate (attributes: AttributeInput\[]) => void A callback that updates the cart attributes. Expects the same `attributes` input that you would provide to the Storefront API's `cartAttributesUpdate` mutation. * cartCreate (cart: CartInput) => void A callback that creates a cart. Expects the same input you would provide to the Storefront API's `cartCreate` mutation. * cartFragment string The fragment used to query the cart object for all queries and mutations. * discountCodesUpdate (discountCodes: string\[]) => void A callback that updates the cart's discount codes. Expects the same `codes` input that you would provide to the Storefront API's `cartDiscountCodesUpdate` mutation. * lines Array\ The cart lines. * linesAdd (lines: CartLineInput\[]) => void A callback that adds lines to the cart. Expects the same `lines` input that you would provide to the Storefront API's `cartLinesAdd` mutation. If a cart doesn't already exist, then it will create the cart for you. * linesRemove (lines: string\[]) => void A callback that removes lines from the cart. Expects the same `lines` input that you would provide to the Storefront API's `cartLinesRemove` mutation. Only lines that are included in the `lines` parameter will be in the cart afterwards. * linesUpdate (lines: CartLineUpdateInput\[]) => void A callback that updates lines in the cart. Expects the same `lines` input that you would provide to the Storefront API's `cartLinesUpdate` mutation. If a line item is not included in the `lines` parameter, it will still exist in the cart and will not be changed. * noteUpdate (note: string) => void A callback that updates the note in the cart. Expects the same `note` input that you would provide to the Storefront API's `cartNoteUpdate` mutation. * status CartStatus The status of the cart. This returns `uninitialized` when the cart is not yet created, `creating` when the cart is being created, `fetching` when an existing cart is being fetched, `updating` when the cart is updating, and `idle` when the cart isn't being created or updated. * buyerIdentity CartBuyerIdentity The cart's buyer identity. * cartReady boolean A boolean indicating if the cart is ready to be interacted with. * checkoutUrl string The checkout URL for the cart, if the cart has been created in the Storefront API. * cost CartCost The cost for the cart, including the subtotal, total, taxes, and duties. * discountCodes CartDiscountCode\[] The discount codes applied to the cart. * error unknown If an error occurred on the previous cart action, then `error` will exist and `cart` will be put back into the last valid status it was in. * id string The cart's ID if it has been created through the Storefront API. * note string The cart's note. * totalQuantity number The total number of items in the cart, across all lines. If there are no lines, then the value is 0. ### CartWithActionsDocs * attributes The cart's attributes. ```ts Attribute[] ``` * buyerIdentity The cart's buyer identity. ```ts CartBuyerIdentity ``` * buyerIdentityUpdate A callback that updates the buyer identity in the cart. Expects the same \`buyerIdentity\` input that you would provide to the Storefront API's \`cartBuyerIdentityUpdate\` mutation. ```ts (buyerIdenity: CartBuyerIdentityInput) => void ``` * cartAttributesUpdate A callback that updates the cart attributes. Expects the same \`attributes\` input that you would provide to the Storefront API's \`cartAttributesUpdate\` mutation. ```ts (attributes: AttributeInput[]) => void ``` * cartCreate A callback that creates a cart. Expects the same input you would provide to the Storefront API's \`cartCreate\` mutation. ```ts (cart: CartInput) => void ``` * cartFragment The fragment used to query the cart object for all queries and mutations. ```ts string ``` * cartReady A boolean indicating if the cart is ready to be interacted with. ```ts boolean ``` * checkoutUrl The checkout URL for the cart, if the cart has been created in the Storefront API. ```ts string ``` * cost The cost for the cart, including the subtotal, total, taxes, and duties. ```ts CartCost ``` * discountCodes The discount codes applied to the cart. ```ts CartDiscountCode[] ``` * discountCodesUpdate A callback that updates the cart's discount codes. Expects the same \`codes\` input that you would provide to the Storefront API's \`cartDiscountCodesUpdate\` mutation. ```ts (discountCodes: string[]) => void ``` * error If an error occurred on the previous cart action, then \`error\` will exist and \`cart\` will be put back into the last valid status it was in. ```ts unknown ``` * id The cart's ID if it has been created through the Storefront API. ```ts string ``` * lines The cart lines. ```ts Array ``` * linesAdd A callback that adds lines to the cart. Expects the same \`lines\` input that you would provide to the Storefront API's \`cartLinesAdd\` mutation. If a cart doesn't already exist, then it will create the cart for you. ```ts (lines: CartLineInput[]) => void ``` * linesRemove A callback that removes lines from the cart. Expects the same \`lines\` input that you would provide to the Storefront API's \`cartLinesRemove\` mutation. Only lines that are included in the \`lines\` parameter will be in the cart afterwards. ```ts (lines: string[]) => void ``` * linesUpdate A callback that updates lines in the cart. Expects the same \`lines\` input that you would provide to the Storefront API's \`cartLinesUpdate\` mutation. If a line item is not included in the \`lines\` parameter, it will still exist in the cart and will not be changed. ```ts (lines: CartLineUpdateInput[]) => void ``` * note The cart's note. ```ts string ``` * noteUpdate A callback that updates the note in the cart. Expects the same \`note\` input that you would provide to the Storefront API's \`cartNoteUpdate\` mutation. ```ts (note: string) => void ``` * status The status of the cart. This returns \`uninitialized\` when the cart is not yet created, \`creating\` when the cart is being created, \`fetching\` when an existing cart is being fetched, \`updating\` when the cart is updating, and \`idle\` when the cart isn't being created or updated. ```ts CartStatus ``` * totalQuantity The total number of items in the cart, across all lines. If there are no lines, then the value is 0. ```ts number ``` ```ts export interface CartWithActionsDocs extends CartBase, CartActions {} ``` ### CartStatus ```ts CartState['status'] ``` ### CartState ```ts {status: 'uninitialized'; error?: string} | {status: 'fetching'} | {status: 'creating'} | {status: 'updating'; cart: Cart; lastValidCart: Cart} | {status: 'idle'; cart: Cart; error?: string} ``` ### Cart ```ts PartialDeep ``` ### Examples * #### Example code ##### Description I am the default example ##### JavaScript ```jsx import {CartProvider, useCart} from '@shopify/hydrogen-react'; export function App() { { console.log('a line is being added'); }} onLineAddComplete={() => { console.log('a line has been added'); }} > ; } function CartComponent() { const {linesAdd, status} = useCart(); const merchandise = {merchandiseId: '{id-here}'}; return (
Cart Status: {status}
); } ``` ##### TypeScript ```tsx import {CartProvider, useCart} from '@shopify/hydrogen-react'; import type {CartLineInput} from '@shopify/hydrogen-react/storefront-api-types'; export function App() { { console.log('a line is being added'); }} onLineAddComplete={() => { console.log('a line has been added'); }} > ; } function CartComponent() { const {linesAdd, status} = useCart(); const merchandise: CartLineInput = {merchandiseId: '{id-here}'}; return (
Cart Status: {status}
); } ``` ## Related [![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/api/hydrogen-react/components/CartProvider) [CartProvider](https://shopify.dev/api/hydrogen-react/components/CartProvider)