@thoughtindustries/cart

Cart components relate to the merchandise that a customer intends to purchase.

Table of contents:

• Cart
• CartButton
• Core cart components
  • AddToCartButton
  • CartCheckoutButton
  • CartUIProvider
  • CartProvider
• Core cart hooks
  • useCartCheckout
  • useCartUI
  • useCart

Cart

The Cart component takes a checkout url to handle the checkout redirection, and optional properties to customize price formatting. It provides access to both UI behavior (like: to toggle cart modal) and callback functions to manage a local cart object.

Example code

import { Cart } from '@thoughtindustries/cart';

export function MyComponent() {
  // ...

  return (
    <Cart checkoutUrl="/checkout">{/* Your JSX */}</Cart>
  );
}

Props

| Name | Required | Type | Description | | -------- | -------- | ----------------------------- | ------------------------- | | children | Yes | ReactNode | Any ReactNode elements. | | checkoutUrl | Yes | string | The URL for the checkout for this cart. | | priceFormat | No | (priceInCents: number) => string | A callback that is invoked to format monetary value with currency. It takes a number value for the price in cent unit and return the formatted value. Default value uses Intl.NumberFormat with props companyDefaultLocale and/or currencyCode to enable locale-specific currency formatting. | | companyDefaultLocale | No | string | A locale value to format price when prop priceFormat is not specified. Used to speficy the locale in Intl.NumberFormat. Default to en-US. | | currencyCode | No | string | A currency code value to format price when prop priceFormat is not specified. Used to speficy the currency code in Intl.NumberFormat. Default to USD. |

CartButton

The CartButton component is a client component that displays the current item count in the cart, and handle click event to toggle the cart modal. It must be a descendent of the Cart component.

Example code

import { Cart, CartButton } from '@thoughtindustries/cart';

export function MyComponent() {
  // ...

  return (
    <Cart checkoutUrl="/checkout">
      <CartButton />
    </Cart>
  );
}

Related components

• Cart

Core cart components

Core cart components are objects that contain all of business logic for the cart concept that they represent. They're used to parse and process data.

AddToCartButton

The AddToCartButton component renders a button that adds a purchaseable item to the cart when pressed. With additional props, it will follow up with step to either open the cart modal or take the user directly to the checkout flow. It must be a descendent of the CartUIProvider component.

Example code

import { CartUIProvider, AddToCartButton, EcommItemType } from '@thoughtindustries/cart';

export function MyComponent() {
  // ...

  return (
    <CartUIProvider checkoutUrl="/checkout">
      <AddToCartButton
        purchasableType={EcommItemType.Product}
        purchasable={{id:'product-uuid', priceInCents:1000}}
      >
        Add to Cart
      </AddToCartButton>
    </CartUIProvider>
  );
}

Props

| Name | Required | Type | Description | | ---------------------------- | -------- | ------------------------------------------- | ----------- | | children | Yes | ReactNode | Any ReactNode elements. | | shouldOpenCart | No | boolean | Option to open cart modal as a follow-up action. | | purchasableType | Yes | EcommItemType | Type of purchaseable item (one of the ecommerce item type). | | purchasable | Yes | PurchaseableItem | Object of the purchaseable item. | | coupon | No | Coupon | Optional coupon object. | | interval | No | CartItemInterval | Optional payment interval (one of the interval type). | | quantity | No | number | Optional quantity (a default value will be applied when not sepcified). | | buttonRef | No | Ref<HTMLButtonElement> | A reference to the underlying button. |

Related components

• CartUIProvider
• CartProvider

Related hooks

• useCartUI
• useCart
• useCartCheckout

CartCheckoutButton

The CartCheckoutButton component renders a button that redirects to the checkout URL for the cart. It must be a descendent of a CartProvider component.

Example code

import { CartCheckoutButton, CartProvider } from '@thoughtindustries/cart';

export function MyComponent() {
  return (
    <CartProvider checkoutUrl="/checkout">
      <CartCheckoutButton>Checkout</CartCheckoutButton>
    </CartProvider>
  )
}

Props

| Name | Required | Type | Description | | ----------- | -------- | ---------------------- | ---------------------- | | children | Yes | ReactNode | A ReactNode element. | | buttonRef | No | Ref<HTMLButtonElement> | A reference to the underlying button. |

Related components

• CartProvider

Related hooks

• useCart
• useCartCheckout

CartProvider

The CartProvider component creates a context for using a cart. It creates a cart object and callbacks that can be accessed by any descendent component using the useCart hook and related hooks.

You must use this component if you want to use the useCart hook or related hooks, or if you would like to use the AddToCartButton component.

Example code

import { CartProvider } from '@thoughtindustries/cart';

export function App() {
  return <CartProvider>{/* Your JSX */}</CartProvider>;
}

Props

| Name | Required | Type | Description | | ---------------------- | -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | children | Yes | React.ReactNode | Any ReactNode elements. | | checkoutUrl | Yes | string | The URL for the checkout for this cart. |

Related hooks

• useCart

CartUIProvider

The CartUIProvider component defines the behavior that occurs when a user is interacting with a cart (for example, opening or closing it), it also creates a cart object and provides callbacks that can be accessed by any descendent component using the useCartUI hook, the useCart hook, and related hooks. This component renders the CartProvider to provides any of its descendant access to the context of CartProvider.

You must use this component if you want to use the useCartUI hook, the useCart hook or related hooks, or if you would like to use the AddToCartButton component.

Example code

import { CartUIProvider } from '@thoughtindustries/cart';

export function App() {
  return <CartProvider>{/* Your JSX */}</CartProvider>;
}

Props

| Name | Required | Type | Description | | ---------------------- | -------- | ---------------------------- | ------------------------------------------------------------- | | children | Yes | React.ReactNode | Any ReactNode elements. | | checkoutUrl | Yes | string | The URL for the checkout for this cart. |

Related components

• CartProvider

Core cart hooks

Core cart hooks are functions that allow you to use state and other methods inside cart components.

useCartCheckout

The useCartCheckout hook provides access to the cart checkout process. It must be a descendent of a CartProvider component.

Example code

import { CartProvider, useCartCheckout } from '@thoughtindustries/cart';

export function MyComponent() {
  return (
    <CartProvider checkoutUrl="/checkout">
      <CartCheckoutButton />
    </CartProvider>
  );
}

export function CartCheckoutButton() {
  const { isCheckoutRequested, startCheckout } = useCartCheckout();

  return (
    <button disabled={isCheckoutRequested} onClick={startCheckout}>
      {/* Your JSX */}
    </button>
  );
}

Return value

The useCartCheckout hook returns an object with the following keys:

| Name | Required | Description | | ------------------------------- | -------- | ----------- | | isCheckoutRequested | Yes | This indicates if the cart checkout process has already requested. | | startCheckout | Yes | A callback that starts the cart checkout process. |

Related hooks

• useCart

useCartUI

The useCartUI hook provides access to the cart UI context. It must be a descendent of a CartUIProvider component.

Example code

import { CartUIProvider, useCartUI } from '@thoughtindustries/cart';

export function MyComponent() {
  return (
    <CartUIProvider checkoutUrl="/checkout">
      <CartToggle />
    </CartUIProvider>
  );
}

export function CartToggle() {
  const { isCartOpen, openCart } = useCartUI();

  return (
    <button disabled={isCartOpen} onClick={openCart}>
      {/* Your JSX */}
    </button>
  );
}

Return value

The useCartUI hook returns an object with the following keys:

| Name | Required | Description | | ------------------------------- | -------- | ----------- | | isCartOpen | Yes | Boolean value indicating if the cart (modal) is open. | | openCart | Yes | A callback to open cart. | | closeCart | Yes | A callback to close cart. | | toggleCart | Yes | A callback to toggle cart to open or to close. |

Related components

• CartUIProvider

useCart

The useCart hook provides access to the cart object. It must be a descendent of a CartProvider component.

Example code

import { CartProvider, useCart } from '@thoughtindustries/cart';

export function MyComponent() {
  return (
    <CartProvider checkoutUrl="/checkout">
      <CartTotalQuantity />
    </CartProvider>
  );
}

export function CartTotalQuantity() {
  const { totalQuantity } = useCart();

  return (
    <>
      {totalQuantity}
    </>
  );
}

Return value

The useCart hook returns an object with the following keys:

| Name | Required | Description | | ------------------------------- | -------- | ----------- | | items | Yes | The cart items. | | checkoutUrl | Yes | The URL for the checkout for this cart. | | isInitialized | Yes | This indicates if the cart is initialized. The initialization process will trigger once the CartProvider component is mounted. | | addPurchaseableItem | Yes | A callback that adds purchaseable item to the cart. Expects the AddPurchaseableItemPayload input. | | removeItem | Yes | A callback that removes item from the cart. Expects the CartItem input. | | toggleItemInstructorAccess | Yes | A callback that updates item variation label for instructor access in the cart. Expects the CartItem. | | totalQuantity | Yes | The total number of items in the cart, across all items. If there are no items, then the value is 0. |

Related components

• CartProvider