Choose a version:

useCart
hook

Provides access to the cart object.

Anchor to Props
Props()

useCart hook must be a descendent of a CartProvider component.

Anchor to Props-returnsReturns

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: 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.

UseCartDocs

CartWithActionsDocs

CartWithActionsDocs

type UseCartDocs = () => CartWithActionsDocs;

CartWithActionsDocs

attributes
The cart's attributes.
```
Attribute[]
```
buyerIdentity
The cart's buyer identity.
```
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.
```
(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.
```
(attributes: AttributeInput[]) => void
```
cartCreate
A callback that creates a cart. Expects the same input you would provide to the Storefront API's `cartCreate` mutation.
```
(cart: CartInput) => void
```
cartFragment
The fragment used to query the cart object for all queries and mutations.
```
string
```
cartReady
A boolean indicating if the cart is ready to be interacted with.
```
boolean
```
checkoutUrl
The checkout URL for the cart, if the cart has been created in the Storefront API.
```
string
```
cost
The cost for the cart, including the subtotal, total, taxes, and duties.
```
CartCost
```
discountCodes
The discount codes applied to the cart.
```
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.
```
(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.
```
unknown
```
id
The cart's ID if it has been created through the Storefront API.
```
string
```

lines

The cart lines.

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.
```
(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.
```
(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.
```
(lines: CartLineUpdateInput[]) => void
```
note
The cart's note.
```
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.
```
(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.
```
CartStatus
```
totalQuantity
The total number of items in the cart, across all lines. If there are no lines, then the value is 0.
```
number
```

export interface CartWithActionsDocs extends CartBase, CartActions {}

CartStatus

CartState['status']

CartState

{status: 'uninitialized'; error?: string} | {status: 'fetching'} | {status: 'creating'} | {status: 'updating'; cart: Cart; lastValidCart: Cart} | {status: 'idle'; cart: Cart; error?: string}

Cart

PartialDeep<CartBase, {recurseIntoArrays: true}>

Was this section helpful?

Example code

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');

}}

</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>

);

}

examples

Example code

description

I am the default example

JavaScript

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

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>
  );
}