feature-shopping-list

@evolve-storefront/feature-shopping-list · v1.0.0 · Storybook ↗

Shopping lists: save products to a list from any product page or card, then view and manage the lists. It works in two modes: B2C, with one list per shopper saved through a heart toggle, and B2B, with many named lists per business unit chosen from a picker.

Get started

1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

   pnpm add @evolve-storefront/feature-shopping-list @labdigital/graphql-fetcher @tanstack/react-query graphql next next-intl react sonner

   Requirements7

   @labdigital/graphql-fetcher	>=3
   @tanstack/react-query	>=5
   graphql	>=16
   next	>=16.2.11 <17
   next-intl	>=4
   react	>=19
   sonner	>=2

2. Import its styles in the stylesheet where you load Tailwind. Without them the components render unstyled.

   @import "@evolve-storefront/feature-shopping-list/styles.css";

3. Wrap your app in ShoppingListProvider. Setup lists its props.

4. Add its translations to your message files with evolve messages.

Then render it on a page:

// B2C — heart toggle. Positioning is the consumer's concern (pass className).
import { ShoppingListAddButton } from "@evolve-storefront/feature-shopping-list/shopping-list-add-button";
<ShoppingListAddButton sku={variant.sku} />;

// B2B — list picker (popover / mobile bottom-sheet). Active-list seam is injectable.
import { ShoppingListPickerButton } from "@evolve-storefront/feature-shopping-list/shopping-list-picker-button";
import { useActiveShoppingList } from "@evolve-storefront/feature-shopping-list/hooks";
const { activeShoppingList, setActiveShoppingListId } = useActiveShoppingList(lists);
<ShoppingListPickerButton
  sku={variant.sku}
  activeShoppingList={activeShoppingList}
  setActiveShoppingListId={setActiveShoppingListId}
/>;

Components

What you place on your pages. Each one has a preview, its props, and how to change its layout.

ShoppingListDetailPure presentation for a shopping list — the stable extension seam (§6).

ShoppingListOverviewPure presentation for the multi-list overview — the stable extension seam (§6).

ShoppingListFormShared create/edit form root, built on the evolve-feature-form pattern: a RAC Form whose validationErrors drive display, validated by one exported Zod schema.

ShoppingListAddButtonSingle-list heart toggle.

ShoppingListPickerButtonMulti-list picker (business mode): a list trigger that opens a panel listing every shopping list with a per-list toggle, plus "New shopping list".

ShoppingListDeleteButtonDelete control with a confirmation dialog; compose it into headerActions.

ShoppingListShareButtonOpt-in: create a shareable anonymous list from a set of SKUs and surface the copyable URL plus any SKUs the backend dropped as invalid.

Hooks

9 hooks to read and change the data yourself, for when you build your own UI. The example above only needs useActiveShoppingList. All hooks

More in this package

• Setup and server: what the package needs in your project.
• Advanced: contexts, graphql documents, data and cache helpers, schemas, other functions and constants, types.