@thoughtindustries/cart

1.2.5 • Public • Published

@thoughtindustries/cart

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

Table of contents:

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

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.

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.

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.

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.

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.

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.

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.

Readme

Keywords

none

Package Sidebar

Install

npm i @thoughtindustries/cart

Weekly Downloads

5

Version

1.2.5

License

MIT

Unpacked Size

62.5 kB

Total Files

42

Last publish

Collaborators

  • tidev