feat: Add items stock/backorder messages to cart page (#2758)

Tharaae · web-flow · commit d78bc85fa4a6 · 2026-02-09T22:46:18.000Z
* feat: Add items stock/backorder messages to cart page

* feat: Add items stock/backorder messages to cart page - Apply UI comments

* feat: Add items stock/backorder messages to cart page - Apply review comments
diff --git a/.changeset/tender-toys-heal.md b/.changeset/tender-toys-heal.md
@@ -0,0 +1,15 @@
+---
+"@bigcommerce/catalyst-core": minor
+---
+
+Add the following messages to each line item on cart page based on store inventory settings:
+- Fully/partially out-of-stock message if enabled on the store and the line item is currently out of stock
+- Ready-to-ship quantity if enabled on the store
+- Backordered quantity if enabled on the store
+
+## Migration
+For existing Catalyst stores, to get the newly added feature, simply rebase the existing code with the new release code. The files to be rebased for this change to be applied are:
+- core/app/[locale]/(default)/cart/page-data.ts
+- core/app/[locale]/(default)/cart/page.tsx
+- core/messages/en.json
+- core/vibes/soul/sections/cart/client.tsx
diff --git a/core/app/[locale]/(default)/cart/page-data.ts b/core/app/[locale]/(default)/cart/page-data.ts
@@ -56,6 +56,12 @@ export const PhysicalItemFragment = graphql(`
       }
     }
     url
+    stockPosition {
+      backorderMessage
+      quantityOnHand
+      quantityBackordered
+      quantityOutOfStock
+    }
   }
 `);
 
@@ -206,6 +212,13 @@ const CartPageQuery = graphql(
     query CartPageQuery($cartId: String, $currencyCode: currencyCode) {
       site {
         settings {
+          inventory {
+            defaultOutOfStockMessage
+            showOutOfStockMessage
+            showBackorderMessage
+            showQuantityOnBackorder
+            showQuantityOnHand
+          }
           url {
             checkoutUrl
           }
diff --git a/core/app/[locale]/(default)/cart/page.tsx b/core/app/[locale]/(default)/cart/page.tsx
@@ -125,6 +125,47 @@ export default async function Cart({ params }: Props) {
       };
     }
 
+    let inventoryMessages;
+
+    if (item.__typename === 'CartPhysicalItem') {
+      if (item.stockPosition?.quantityOutOfStock === item.quantity) {
+        inventoryMessages = {
+          outOfStockMessage: data.site.settings?.inventory?.showOutOfStockMessage
+            ? data.site.settings.inventory.defaultOutOfStockMessage
+            : undefined,
+        };
+      } else {
+        inventoryMessages = {
+          quantityReadyToShipMessage:
+            data.site.settings?.inventory?.showQuantityOnHand &&
+            !!item.stockPosition?.quantityOnHand
+              ? t('quantityReadyToShip', {
+                  quantity: Number(item.stockPosition.quantityOnHand),
+                })
+              : undefined,
+          quantityBackorderedMessage:
+            data.site.settings?.inventory?.showQuantityOnBackorder &&
+            !!item.stockPosition?.quantityBackordered
+              ? t('quantityOnBackorder', {
+                  quantity: Number(item.stockPosition.quantityBackordered),
+                })
+              : undefined,
+          quantityOutOfStockMessage:
+            data.site.settings?.inventory?.showOutOfStockMessage &&
+            !!item.stockPosition?.quantityOutOfStock
+              ? t('partiallyAvailable', {
+                  quantity: item.quantity - Number(item.stockPosition.quantityOutOfStock),
+                })
+              : undefined,
+          backorderMessage:
+            data.site.settings?.inventory?.showBackorderMessage &&
+            !!item.stockPosition?.quantityBackordered
+              ? (item.stockPosition.backorderMessage ?? undefined)
+              : undefined,
+        };
+      }
+    }
+
     return {
       typename: item.__typename,
       id: item.entityId,
@@ -165,6 +206,7 @@ export default async function Cart({ params }: Props) {
       selectedOptions: item.selectedOptions,
       productEntityId: item.productEntityId,
       variantEntityId: item.variantEntityId,
+      inventoryMessages,
     };
   });
 
diff --git a/core/messages/en.json b/core/messages/en.json
@@ -370,6 +370,9 @@
     "cartUpdateInProgress": "You have a cart update in progress. Are you sure you want to leave this page? Your changes may be lost.",
     "originalPrice": "Original price was {price}.",
     "currentPrice": "Current price is {price}.",
+    "quantityReadyToShip": "{quantity, number} ready to ship",
+    "quantityOnBackorder": "{quantity, number} will be backordered",
+    "partiallyAvailable": "Only {quantity, number} available",
     "CheckoutSummary": {
       "title": "Summary",
       "subTotal": "Subtotal",
diff --git a/core/vibes/soul/sections/cart/client.tsx b/core/vibes/soul/sections/cart/client.tsx
@@ -34,6 +34,14 @@ import { CartEmptyState } from '.';
 
 type Action<State, Payload> = (state: Awaited<State>, payload: Payload) => State | Promise<State>;
 
+interface CartLineIteminventoryMessages {
+  outOfStockMessage?: string;
+  quantityReadyToShipMessage?: string;
+  quantityBackorderedMessage?: string;
+  quantityOutOfStockMessage?: string;
+  backorderMessage?: string;
+}
+
 export interface CartLineItem {
   typename: string;
   id: string;
@@ -44,6 +52,7 @@ export interface CartLineItem {
   price: string;
   salePrice?: string;
   href?: string;
+  inventoryMessages?: CartLineIteminventoryMessages;
 }
 
 export interface CartGiftCertificateLineItem extends CartLineItem {
@@ -563,7 +572,7 @@ function CounterForm({
       <input {...getInputProps(fields.id, { type: 'hidden' })} key={fields.id.id} />
       <div className="flex w-full flex-wrap items-center gap-x-5 gap-y-2">
         {lineItem.salePrice && lineItem.salePrice !== lineItem.price ? (
-          <span className="font-medium @xl:ml-auto">
+          <span className="mt-3 self-start font-medium @xl:ml-auto">
             <span className="sr-only">{t('originalPrice', { price: lineItem.price })}</span>
             <span aria-hidden="true" className="line-through">
               {lineItem.price}
@@ -572,65 +581,101 @@ function CounterForm({
             <span aria-hidden="true">{lineItem.salePrice}</span>
           </span>
         ) : (
-          <span className="font-medium @xl:ml-auto">{lineItem.price}</span>
+          <span className="mt-3 self-start font-medium @xl:ml-auto">{lineItem.price}</span>
         )}
-        {/* Counter */}
-        <div className="flex items-center rounded-lg border border-[var(--cart-counter-border,hsl(var(--contrast-100)))]">
-          <button
-            aria-label={decrementLabel}
-            className={clsx(
-              'group rounded-l-lg bg-[var(--cart-counter-background,hsl(var(--background)))] p-3 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--cart-focus,hsl(var(--primary)))] disabled:cursor-not-allowed',
-              lineItem.quantity === 1
-                ? 'opacity-50'
-                : 'hover:bg-[var(--cart-counter-background-hover,hsl(var(--contrast-100)/50%))]',
-            )}
-            disabled={lineItem.quantity === 1}
-            name="intent"
-            type="submit"
-            value="decrement"
-          >
-            <Minus
+        <div className="flex size-min flex-col gap-y-0">
+          <div className="mb-1 mt-1 flex items-center gap-x-5">
+            {/* Counter */}
+            <div
               className={clsx(
-                'text-[var(--cart-counter-icon,hsl(var(--contrast-300)))] transition-colors duration-300',
-                lineItem.quantity !== 1 &&
-                  'group-hover:text-[var(--cart-counter-icon-hover,hsl(var(--foreground)))]',
+                'flex items-center rounded-lg border border-[var(--cart-counter-border,hsl(var(--contrast-100)))]',
+                (lineItem.inventoryMessages?.outOfStockMessage != null ||
+                  lineItem.inventoryMessages?.quantityOutOfStockMessage != null) &&
+                  'border-red-500',
               )}
-              size={18}
-              strokeWidth={1.5}
-            />
-          </button>
-          <span className="flex w-8 select-none justify-center focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--cart-focus,hsl(var(--primary)))]">
-            {lineItem.quantity}
-          </span>
-          <button
-            aria-label={incrementLabel}
-            className={clsx(
-              'group rounded-r-lg bg-[var(--cart-counter-background,hsl(var(--background)))] p-3 transition-colors duration-300 hover:bg-[var(--cart-counter-background-hover,hsl(var(--contrast-100)/50%))] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--cart-focus,hsl(var(--primary)))] disabled:cursor-not-allowed',
-            )}
-            name="intent"
-            type="submit"
-            value="increment"
-          >
-            <Plus
-              className="text-[var(--cart-counter-icon,hsl(var(--contrast-300)))] transition-colors duration-300 group-hover:text-[var(--cart-counter-icon-hover,hsl(var(--foreground)))]"
-              size={18}
-              strokeWidth={1.5}
-            />
-          </button>
+            >
+              <button
+                aria-label={decrementLabel}
+                className={clsx(
+                  'group rounded-l-lg bg-[var(--cart-counter-background,hsl(var(--background)))] p-3 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--cart-focus,hsl(var(--primary)))] disabled:cursor-not-allowed',
+                  lineItem.quantity === 1
+                    ? 'opacity-50'
+                    : 'hover:bg-[var(--cart-counter-background-hover,hsl(var(--contrast-100)/50%))]',
+                )}
+                disabled={lineItem.quantity === 1}
+                name="intent"
+                type="submit"
+                value="decrement"
+              >
+                <Minus
+                  className={clsx(
+                    'text-[var(--cart-counter-icon,hsl(var(--contrast-300)))] transition-colors duration-300',
+                    lineItem.quantity !== 1 &&
+                      'group-hover:text-[var(--cart-counter-icon-hover,hsl(var(--foreground)))]',
+                  )}
+                  size={18}
+                  strokeWidth={1.5}
+                />
+              </button>
+              <span className="flex w-8 select-none justify-center focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--cart-focus,hsl(var(--primary)))]">
+                {lineItem.quantity}
+              </span>
+              <button
+                aria-label={incrementLabel}
+                className={clsx(
+                  'group rounded-r-lg bg-[var(--cart-counter-background,hsl(var(--background)))] p-3 transition-colors duration-300 hover:bg-[var(--cart-counter-background-hover,hsl(var(--contrast-100)/50%))] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--cart-focus,hsl(var(--primary)))] disabled:cursor-not-allowed',
+                )}
+                name="intent"
+                type="submit"
+                value="increment"
+              >
+                <Plus
+                  className="text-[var(--cart-counter-icon,hsl(var(--contrast-300)))] transition-colors duration-300 group-hover:text-[var(--cart-counter-icon-hover,hsl(var(--foreground)))]"
+                  size={18}
+                  strokeWidth={1.5}
+                />
+              </button>
+            </div>
+            <button
+              aria-label={deleteLabel}
+              className="group -ml-1 mt-1.5 flex h-8 w-8 shrink-0 items-center justify-center self-start rounded-full transition-colors duration-300 hover:bg-[var(--cart-button-background,hsl(var(--contrast-100)))] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--cart-focus,hsl(var(--primary)))] focus-visible:ring-offset-4"
+              name="intent"
+              type="submit"
+              value="delete"
+            >
+              <Trash2
+                className="text-[var(--cart-icon,hsl(var(--contrast-300)))] group-hover:text-[var(--cart-icon-hover,hsl(var(--foreground)))]"
+                size={20}
+                strokeWidth={1}
+              />
+            </button>
+          </div>
+          {lineItem.inventoryMessages?.outOfStockMessage != null && (
+            <span className="text-xs/5 font-light text-red-500">
+              {lineItem.inventoryMessages.outOfStockMessage}
+            </span>
+          )}
+          {lineItem.inventoryMessages?.quantityOutOfStockMessage != null && (
+            <span className="mb-3 text-xs/5 font-light text-red-500">
+              {lineItem.inventoryMessages.quantityOutOfStockMessage}
+            </span>
+          )}
+          {lineItem.inventoryMessages?.quantityReadyToShipMessage != null && (
+            <span className="text-xs/5 font-light">
+              {lineItem.inventoryMessages.quantityReadyToShipMessage}
+            </span>
+          )}
+          {lineItem.inventoryMessages?.quantityBackorderedMessage != null && (
+            <span className="text-xs/5 font-light">
+              {lineItem.inventoryMessages.quantityBackorderedMessage}
+            </span>
+          )}
+          {lineItem.inventoryMessages?.backorderMessage != null && (
+            <span className="text-xs/5 font-light">
+              {lineItem.inventoryMessages.backorderMessage}
+            </span>
+          )}
         </div>
-        <button
-          aria-label={deleteLabel}
-          className="group -ml-1 flex h-8 w-8 shrink-0 items-center justify-center rounded-full transition-colors duration-300 hover:bg-[var(--cart-button-background,hsl(var(--contrast-100)))] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--cart-focus,hsl(var(--primary)))] focus-visible:ring-offset-4"
-          name="intent"
-          type="submit"
-          value="delete"
-        >
-          <Trash2
-            className="text-[var(--cart-icon,hsl(var(--contrast-300)))] group-hover:text-[var(--cart-icon-hover,hsl(var(--foreground)))]"
-            size={20}
-            strokeWidth={1}
-          />
-        </button>
       </div>
     </form>
   );
