---
title: useOptimisticCart
description: >-
  The useOptimisticCart takes an existing cart object, processes all pending
  cart actions, and locally mutates the cart with optimistic state.
api_version: 2026-04
api_name: hydrogen
source_url:
  html: 'https://shopify.dev/docs/api/hydrogen/latest/hooks/useoptimisticcart'
  md: 'https://shopify.dev/docs/api/hydrogen/latest/hooks/useoptimisticcart.md'
---

# useOptimisticCart

The `useOptimisticCart` takes an existing cart object, processes all pending cart actions, and locally mutates the cart with optimistic state. An optimistic cart makes cart actions immediately render in the browser while actions sync to the server. This increases the perceived performance of the application.

## use​Optimistic​Cart(**[cart](#props-propertydetail-cart)**​)

### Parameters

* **cart**

  **DefaultCart**

  The cart object from `context.cart.get()` returned by a server loader.

### Returns

* **OptimisticCart\<DefaultCart = { lines?: { nodes: Array<{id: string; quantity: number; merchandise: {is: string}}>; }; }>**

  A new cart object augmented with optimistic state for `lines` and `totalQuantity`. Each cart line item that is optimistically added includes an `isOptimistic` property. Also if the cart has *any* optimistic state, a root property `isOptimistic` will be set to `true`.

### DefaultCart

```ts
Promise<CartReturn | null> | CartReturn | null
```

### CartReturn

```ts
Cart & {
  errors?: StorefrontApiErrors;
}
```

### Cart

* attributes

  The cart's attributes.

  ```ts
  { __typename?: "Attribute"; key?: string; value?: string; }[]
  ```

* buyerIdentity

  The cart's buyer identity.

  ```ts
  CartType['buyerIdentity']
  ```

* 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
  CartType['cost']
  ```

* discountCodes

  The discount codes applied to the cart.

  ```ts
  { __typename?: "CartDiscountCode"; applicable?: boolean; code?: string; }[]
  ```

* id

  The cart's ID if it has been created through the Storefront API.

  ```ts
  string
  ```

* lines

  The cart lines.

  ```ts
  Array<CartLine | ComponentizableCartLine>
  ```

* note

  The cart's note.

  ```ts
  string
  ```

* totalQuantity

  The total number of items in the cart, across all lines. If there are no lines, then the value is 0.

  ```ts
  number
  ```

### StorefrontApiErrors

```ts
JsonGraphQLError[] | undefined
```

### JsonGraphQLError

* extensions

  Reserved for implementors to extend the protocol however they see fit, and hence there are no additional restrictions on its contents.

  ```ts
  { [key: string]: unknown; }
  ```

* locations

  If an error can be associated to a particular point in the requested GraphQL document, it should contain a list of locations.

  ```ts
  { line: number; column: number; }[]
  ```

* message

  ```ts
  string
  ```

* name

  ```ts
  string
  ```

* path

  If an error can be associated to a particular field in the GraphQL result, it \_must\_ contain an entry with the key \`path\` that details the path of the response field which experienced the error. This allows clients to identify whether a null result is intentional or caused by a runtime error.

  ```ts
  (string | number)[]
  ```

* stack

  ```ts
  string
  ```

### OptimisticCart

```ts
T extends undefined | null
  ? // This is the null/undefined case, where the cart has yet to be created.
    // But we still need to provide an optimistic cart object.
    {
      isOptimistic?: boolean;
      lines: {
        nodes: Array<OptimisticCartLine>;
      };
      totalQuantity?: number;
    } & Omit<PartialDeep<CartReturn>, 'lines'>
  : Omit<T, 'lines'> & {
      isOptimistic?: boolean;
      lines: {
        nodes: Array<OptimisticCartLine<T>>;
      };
      totalQuantity?: number;
    }
```

### OptimisticCartLine

```ts
T extends LikeACart
  ? T['lines']['nodes'][number] & {isOptimistic?: boolean}
  : T & {isOptimistic?: boolean}
```

### LikeACart

* lines

  ```ts
  { nodes: unknown[]; }
  ```

Examples

### Examples

* #### Example code

  ##### JavaScript

  ```jsx
  import {Link} from 'react-router';
  import {CartForm, useOptimisticCart} from '@shopify/hydrogen';

  // Root loader returns the cart data
  export async function loader({context}) {
    return {
      cart: context.cart.get(),
    };
  }

  // The cart component renders each line item in the cart.
  export function Cart({cart}) {
    // `useOptimisticCart` adds optimistic line items to the cart.
    // These line items are displayed in the cart until the server responds.
    const optimisticCart = useOptimisticCart(cart);

    if (!optimisticCart?.lines?.nodes?.length) return <p>Nothing in cart</p>;

    return optimisticCart.lines.nodes.map((line) => (
      <div key={line.id}>
        <Link to={`/products${line.merchandise.product.handle}`}>
          {line.merchandise.product.title}
        </Link>
        <CartForm
          route="/cart"
          action={CartForm.ACTIONS.LinesRemove}
          inputs={{lineIds: [line.id]}}
        >
          {/* Each line item has an `isOptimistic` property. Optimistic line items
          should have actions disabled */}
          <button type="submit" disabled={!!line.isOptimistic}>
            Remove
          </button>
        </CartForm>
      </div>
    ));
  }
  ```

  ##### TypeScript

  ```tsx
  import {type LoaderFunctionArgs} from 'react-router';
  import {Link} from 'react-router';
  import {CartForm, useOptimisticCart} from '@shopify/hydrogen';
  import type {Cart} from '@shopify/hydrogen/storefront-api-types';

  // Root loader returns the cart data
  export async function loader({context}: LoaderFunctionArgs) {
    return {
      cart: context.cart.get(),
    };
  }

  // The cart component renders each line item in the cart.
  export function Cart({cart: originalCart}: {cart: Cart}) {
    // `useOptimisticCart` adds optimistic line items to the cart.
    // These line items are displayed in the cart until the server responds.
    const cart = useOptimisticCart(originalCart);
    if (!cart?.lines?.nodes?.length) return <p>Nothing in cart</p>;

    return cart.lines.nodes.map((line) => (
      <div key={line.id}>
        <Link to={`/products${line.merchandise.product.handle}`}>
          {line.merchandise.product.title}
        </Link>
        <CartForm
          route="/cart"
          action={CartForm.ACTIONS.LinesRemove}
          inputs={{lineIds: [line.id]}}
        >
          {/* Each line item has an `isOptimistic` property. Optimistic line items
          should have actions disabled */}
          <button type="submit" disabled={!!line.isOptimistic}>
            Remove
          </button>
        </CartForm>
      </div>
    ));
  }
  ```

***

## Related

[- CartForm](https://shopify.dev/docs/api/hydrogen/2026-04/components/cartform)

***