---
title: useCart
description: Provides access to the cart object.
api_version: 2025-07
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\<CartLine | ComponentizableCartLine>

    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<CartLine | ComponentizableCartLine>
  ```

* 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<CartBase, {recurseIntoArrays: true}>
```

### Examples

* #### Example code

  ##### Description

  I am the default example

  ##### JavaScript

  ```jsx
  import {CartProvider, useCart} from '@shopify/hydrogen-react';

  export function App() {
    <CartProvider
      onLineAdd={() => {
        console.log('a line is being added');
      }}
      onLineAddComplete={() => {
        console.log('a line has been added');
      }}
    >
      <CartComponent />
    </CartProvider>;
  }

  function CartComponent() {
    const {linesAdd, status} = useCart();

    const merchandise = {merchandiseId: '{id-here}'};

    return (
      <div>
        Cart Status: {status}
        <button onClick={() => linesAdd([merchandise])}>Add Line</button>
      </div>
    );
  }
  ```

  ##### TypeScript

  ```tsx
  import {CartProvider, useCart} from '@shopify/hydrogen-react';
  import type {CartLineInput} from '@shopify/hydrogen-react/storefront-api-types';

  export function App() {
    <CartProvider
      onLineAdd={() => {
        console.log('a line is being added');
      }}
      onLineAddComplete={() => {
        console.log('a line has been added');
      }}
    >
      <CartComponent />
    </CartProvider>;
  }

  function CartComponent() {
    const {linesAdd, status} = useCart();

    const merchandise: CartLineInput = {merchandiseId: '{id-here}'};

    return (
      <div>
        Cart Status: {status}
        <button onClick={() => linesAdd([merchandise])}>Add Line</button>
      </div>
    );
  }
  ```

## Related

[- CartProvider](https://shopify.dev/api/hydrogen-react/components/CartProvider)