use-shopping-cart logouse-shopping-cart
Hooks

useCartActions()

New in v4.0.0 - Form-based cart actions built on React 19's useActionState, with pending and error state for each action.

Overview

useCartActions() provides cart operations for the action attribute of forms. Unlike useShoppingCart(), whose methods you call from handlers like onClick, each action reads its input from the form's fields and tracks its own pending and error state.

The actions run in the browser, because the cart lives there. A form only works once React has hydrated; without JavaScript, submitting it does nothing.

When to Use

Use useCartActions() when:

  • Building forms for cart operations
  • You want built-in pending and error states
  • Your product data is already in the form (for example a hidden product field)

Use useShoppingCart() or useOptimisticCart() when:

  • Using onClick handlers
  • Simple button interactions
  • Programmatic cart updates
  • You don't need form-based interactions

Requirements

  • React 19.0.0 or higher
  • use-shopping-cart v4.0.0 or higher

Basic Usage

import { useCartActions } from 'use-shopping-cart'

function ProductCard({ product }) {
  const { addToCartAction, isAddingItem } = useCartActions()

  return (
    <form action={addToCartAction}>
      <input type="hidden" name="product" value={JSON.stringify(product)} />
      <button disabled={isAddingItem}>
        {isAddingItem ? 'Adding...' : 'Add to Cart'}
      </button>
    </form>
  )
}

API

Returned Values

Add Item

  • addToCartAction: Form action for adding items
  • addItemState: { status, error, errorCode, productId }
  • isAddingItem: Boolean pending state

Form fields:

  • product (required): JSON string of product object (max 50,000 chars)
  • count (optional): Positive integer count to add (default: 1)
<form action={addToCartAction}>
  <input type="hidden" name="product" value={JSON.stringify(product)} />
  <input type="number" name="count" defaultValue="1" />
  <button>Add to Cart</button>
</form>

Remove Item

  • removeFromCartAction: Form action for removing items
  • removeItemState: { status, error, errorCode, itemId }
  • isRemovingItem: Boolean pending state

Form fields:

  • itemId (required): ID of the item to remove
<form action={removeFromCartAction}>
  <input type="hidden" name="itemId" value={item.id} />
  <button>Remove</button>
</form>

Update Quantity

  • updateQuantityAction: Form action for setting quantity
  • updateQuantityState: { status, error, errorCode, itemId, quantity }
  • isUpdatingQuantity: Boolean pending state

Form fields:

  • itemId (required): ID of the item
  • quantity (required): Non-negative integer quantity
<form action={updateQuantityAction}>
  <input type="hidden" name="itemId" value={item.id} />
  <input type="number" name="quantity" defaultValue={item.quantity} />
  <button>Update</button>
</form>

Increment Item

  • incrementItemAction: Form action for incrementing
  • incrementItemState: { status, error, errorCode, itemId }
  • isIncrementingItem: Boolean pending state

Form fields:

  • itemId (required): ID of the item
  • count (optional): Positive integer amount to increment (default: 1)

Decrement Item

  • decrementItemAction: Form action for decrementing
  • decrementItemState: { status, error, errorCode, itemId }
  • isDecrementingItem: Boolean pending state

Form fields:

  • itemId (required): ID of the item
  • count (optional): Positive integer amount to decrement (default: 1)

Clear Cart

  • clearCartAction: Form action for clearing cart
  • clearCartState: { status, error, errorCode }
  • isClearingCart: Boolean pending state

Global State

  • isPending: true if ANY action is in progress

Examples

Product Card with Form

function ProductCard({ product }) {
  const { addToCartAction, addItemState, isAddingItem } = useCartActions()

  return (
    <div className="product">
      <h3>{product.name}</h3>
      <p>${product.price / 100}</p>

      <form action={addToCartAction}>
        <input type="hidden" name="product" value={JSON.stringify(product)} />

        <label>
          Quantity:
          <input type="number" name="count" min="1" defaultValue="1" />
        </label>

        <button disabled={isAddingItem}>
          {isAddingItem ? 'Adding...' : 'Add to Cart'}
        </button>

        {addItemState.status === 'success' && (
          <p className="success">✓ Added to cart!</p>
        )}

        {addItemState.error && <p className="error">{addItemState.error}</p>}
      </form>
    </div>
  )
}

Quantity Controls

function CartItem({ item }) {
  const {
    incrementItemAction,
    decrementItemAction,
    removeFromCartAction,
    isPending
  } = useCartActions()

  return (
    <div className="cart-item">
      <h4>{item.name}</h4>

      <div className="quantity-controls">
        <form action={decrementItemAction}>
          <input type="hidden" name="itemId" value={item.id} />
          <button disabled={isPending}>-</button>
        </form>

        <span>{item.quantity}</span>

        <form action={incrementItemAction}>
          <input type="hidden" name="itemId" value={item.id} />
          <button disabled={isPending}>+</button>
        </form>
      </div>

      <form action={removeFromCartAction}>
        <input type="hidden" name="itemId" value={item.id} />
        <button disabled={isPending}>Remove</button>
      </form>
    </div>
  )
}

Comparison: Actions vs Methods

onClick Handler (use useShoppingCart or useOptimisticCart)

function ProductCard({ product }) {
  const { addItem } = useShoppingCart()

  return <button onClick={() => addItem(product)}>Add to Cart</button>
}

Best for:

  • Simple button clicks
  • Programmatic updates
  • Imperative code
  • Quick implementations

Form Action (use useCartActions)

function ProductCard({ product }) {
  const { addToCartAction, isAddingItem } = useCartActions()

  return (
    <form action={addToCartAction}>
      <input type="hidden" name="product" value={JSON.stringify(product)} />
      <button disabled={isAddingItem}>
        {isAddingItem ? 'Adding...' : 'Add to Cart'}
      </button>
    </form>
  )
}

Best for:

  • Forms whose fields carry the input (quantity inputs, hidden product data)
  • Built-in pending and error state per action

Error Handling

When an action fails, its state has status: 'error', a readable error message, and an errorCode to branch on (see error codes). Both are null otherwise.

function ProductCard({ product }) {
  const { addToCartAction, addItemState, isAddingItem } = useCartActions()

  return (
    <form action={addToCartAction}>
      <input type="hidden" name="product" value={JSON.stringify(product)} />

      <button disabled={isAddingItem}>
        {isAddingItem ? 'Adding...' : 'Add to Cart'}
      </button>

      {addItemState.errorCode === 'INVALID_PRODUCT' && (
        <div className="error-message">This product can't be added.</div>
      )}
      {addItemState.status === 'error' &&
        addItemState.errorCode !== 'INVALID_PRODUCT' && (
          <div className="error-message">
            <strong>Error:</strong> {addItemState.error}
          </div>
        )}

      {/* Success feedback */}
      {addItemState.status === 'success' && (
        <div className="success-message">Item added successfully!</div>
      )}
    </form>
  )
}

TypeScript

import { useCartActions } from 'use-shopping-cart'
import type { Product } from 'use-shopping-cart/core'

function ProductCard({ product }: { product: Product }) {
  const { addToCartAction, addItemState, isAddingItem } = useCartActions()

  return (
    <form action={addToCartAction}>
      <input type="hidden" name="product" value={JSON.stringify(product)} />
      <button disabled={isAddingItem}>
        {isAddingItem ? 'Adding...' : 'Add to Cart'}
      </button>
    </form>
  )
}

Benefits

✅ Built-in Pending States - isAddingItem, isPending and the rest, no manual state
✅ Error Handling - Each action's state carries error and errorCode
✅ Plain Forms - Native <form> and <button> elements, so keyboard submit works as usual

Interactive Demo

Cart Display

Total Items: 0

Cart is empty. Add items to see them here!

Bananas product photo

Bananas

Yummy yellow fruit

$4.00

Try Form-Based Actions:

💡 What's happening?

  • Uses HTML forms (progressive enhancement)
  • Automatic loading states with useActionState
  • Built-in error handling and success feedback
  • Works without JavaScript enabled

Try the form-based actions above! Notice how they provide automatic loading states and error handling without any extra state management code.

See Also

On this page

Shopping Cart

Your cart is empty

Try the interactive demos on the docs pages!