Wishlist initialization

The Wishlist initializer configures wishlist functionality including saving items, sharing lists, and managing multiple wishlists. Use initialization to customize wishlist behavior and data models.

Version: 3.5.0

Configuration options

The following table describes the configuration options available for the Wishlist initializer:

Parameter	Type	Req?	Description
`langDefinitions`	`LangDefinitions`	No	Provides language definitions for internationalization (i18n). Overrides dictionary keys for localization or branding.
`isGuestWishlistEnabled`	`boolean`	No	Allows guest users to create and manage wishlists without authentication when set to true. Stores guest wishlists in browser storage.
`storeCode`	`string`	No	Scopes wishlist data (cookies and browser storage) per store. Shares wishlist data across all stores when omitted or set to `default`.
`pageSize`	`number`	No	Number of items per page for wishlist containers. When omitted, the drop-in uses its built-in default.
`guestWishlistTtl`	`Record<string, number>`	No	Per-list expiry, in days, for named guest lists. Keys are list keys (such as `save-for-later`). Each value is the number of days that list persists in browser storage. See Guest list expiry.

Multistore support

In multistore storefronts, pass a storeCode so that the drop-in isolates wishlist data per store view. The Commerce Boilerplate reads the value from the Store header defined in config.json:

1
const headers = getHeaders('wishlist');
2

3
await initializers.mountImmediately(initialize, {
4
  isGuestWishlistEnabled: true,
5
  storeCode: headers.Store,
6
});

When storeCode is set to a value other than default, the drop-in appends __<storeCode> to its browser storage keys and to the wishlist ID cookie. This isolates guest wishlist data and cached authenticated data per store view, and does not change the authoritative wishlist scope in Adobe Commerce. When storeCode is omitted or set to default, the drop-in keeps the original unscoped keys for backward compatibility.

Default configuration

The initializer runs with these defaults when no configuration is provided:

1
import { initializers } from '@dropins/tools/initializer.js';
2
import { initialize } from '@dropins/storefront-wishlist';
3

4
// All configuration options are optional
5
await initializers.mountImmediately(initialize, {
6
  langDefinitions: {}, // Uses built-in English strings
7
  models: {}, // Uses default data models
8
  // Drop-in-specific defaults:
9
  // isGuestWishlistEnabled: undefined // See configuration options below
10
});

Language definitions

Override dictionary keys for localization or branding. The langDefinitions object maps locale keys to custom strings that override default text for the drop-in.

1
import { initializers } from '@dropins/tools/initializer.js';
2
import { initialize } from '@dropins/storefront-wishlist';
3

4
const customStrings = {
5
  'AddToCart': 'Add to Bag',
6
  'Checkout': 'Complete Purchase',
7
  'Price': 'Cost',
8
};
9

10
const langDefinitions = {
11
  default: customStrings,
12
};
13

14
await initializers.mountImmediately(initialize, { langDefinitions });

Customizing data models

Extend or transform data models by providing custom transformer functions. Use the models option to add custom fields or modify existing data structures returned from the backend.

Available models

The following models can be customized through the models configuration option:

The following example shows the general models configuration pattern used across Commerce drop-ins (for reference if you extend the initializer):

1
import { initializers } from '@dropins/tools/initializer.js';
2
import { initialize } from '@dropins/storefront-wishlist';
3

4
const models = {
5
  CustomModel: {
6
    transformer: (data) => ({
7
      // Add custom fields from backend data
8
      customField: data?.custom_field,
9
      promotionBadge: data?.promotion?.label,
10
      // Transform existing fields
11
      displayPrice: data?.price?.value ? `${data.price.value}` : 'N/A',
12
    }),
13
  },
14
};
15

16
await initializers.mountImmediately(initialize, { models });

Drop-in configuration

1
import { initializers } from '@dropins/tools/initializer.js';
2
import { initialize } from '@dropins/storefront-wishlist';
3

4
await initializers.mountImmediately(initialize, {
5
  langDefinitions: {},
6
  isGuestWishlistEnabled: true,
7
});

Guest list expiry

When you render an additional guest list beyond the default wishlist (for example, a “Save for Later” list), you can set how long that list persists in the guest’s browser. Use guestWishlistTtl to map each list key to a number of days:

1
import { initializers } from '@dropins/tools/initializer.js';
2
import { initialize } from '@dropins/storefront-wishlist';
3

4
await initializers.mountImmediately(initialize, {
5
  isGuestWishlistEnabled: true,
6
  guestWishlistTtl: {
7
    'save-for-later': 14, // The guest "Save for Later" list expires after 14 days
8
  },
9
});

Configuration types

The following TypeScript definitions show the structure of each configuration object:

langDefinitions

Maps locale identifiers to dictionaries of key-value pairs. The default locale is used as the fallback when no specific locale matches. Each dictionary key corresponds to a text string used in the drop-in UI.

1
langDefinitions?: {
2
  [locale: string]: {
3
    [key: string]: string;
4
  };
5
};