Cart
Description
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.
✨🎨 View Component in Storybook 🎨✨
Installation
- npm
- Yarn
npm install @thoughtindustries/cart
yarn add @thoughtindustries/cart
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
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
Related hooks
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
Related hooks
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
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
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
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
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. |