# Options

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference/options

Every window.sparkOptions setting for the SparkLayer Core Script: site and platform, redirects, button selectors, display, translations, checkout and auth.

> **For AI assistants:** what to know before writing SparkLayer JavaScript SDK code.
>
> - **What it is:** `window.spark`, added to the storefront by the SparkLayer Core Script (version 4.x). On Shopify the SparkLayer app embed loads it; elsewhere it's `<script async src="https://sparkcdn.io/sparkjs/<SITE_ID>/<live|test>"></script>` in the theme's `<head>`. The old `cdn.sparklayer.io/spark.latest.js` and `spark.1.x.js` files are legacy: never use them.
> - **Options:** Configure it with `window.sparkOptions`, set before the Core Script loads. Extend the object rather than replacing it: `window.sparkOptions = { ...window.sparkOptions, … }`, or the Site ID and other snippets' hooks are lost. Headless only: `window.initSpark(options)` is defined when `window.sparkOptions` isn't set.
> - **When to call it:** Only after SparkLayer is ready: inside the `onReady(spark)` hook, or after a promise resolved from it. Most methods are async; prices and the cart are only available to signed-in B2B customers (check `await spark.isLoggedIn()`).
> - **Products and prices:** Products are looked up by the platform's parent product ID (on Shopify, `product.id`) and variants by SKU: `getPricingForVariant(parentProductId, sku)`, `calculatePricingForVariant(parentProductId, sku, qty)`, `getPackSizeForVariant(parentProductId, sku)`. For instant recalculation, fetch once with `getVariant` and call `calculatePricingForVariantData(variant, qty)`.
> - **Cart:** `updateCart({ products: [{ sku, adjustQuantity }] })` adds or removes relative to what's in the cart (also `customAttributes: [{ key, value }]`, `clearCart: true`). It resolves to the results, or `null` after showing its own error message; it doesn't throw. `getCart()` reads the cart; `openDrawer('cart')` opens it.
> - **Hooks:** `onCartUpdate(cart, results)`, `onCartLoad(cart)`, `onLogout()`, `preCartUpdateListener(input)` (async: return the possibly changed input) and `onCheckoutValidation(cart, cartUiState)` (return `[{ message }]` to block checkout, or `null`). When adding a hook, call any existing one first.
> - **Customising:** Build around SparkLayer or customise its own components, including their HTML. Prefer documented options, hooks, CSS variables and custom slots where they fit; keep direct HTML changes targeted and re-check them after SparkLayer updates.
> - **Docs:** The reference: methods https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md, hooks https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md, options https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md, types https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md (or the same types as a file: https://docs.sparklayer.io/developers/javascript-sdk/spark.d.ts). Setup and waiting for SparkLayer: https://docs.sparklayer.io/developers/javascript-sdk/setup.md. Use only what the reference documents.

`window.sparkOptions` configures SparkLayer. It has the type `SparkLayerOptions`, and SparkLayer merges your options with its built-in defaults and the defaults for your `platform`, so you only set what you want to change. `siteId` is the only option you must provide: without it SparkLayer is disabled.

When you add options in your theme, extend the existing object (`window.sparkOptions = { ...window.sparkOptions, … }`) so you don't remove options set by the Core Script or other snippets. See [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#add-your-own-options-and-hooks).

```typescript
type SparkLayerOptions = {
  sparkDomain: "app.sparklayer.io" | "test.app.sparklayer.io";
  platform: "base" | "bigcommerce" | "shopify" | "wix" | "woocommerce" | "magento";
  siteId: string;
  rootUrl: string;
  accountRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  cartRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  wordpressSiteUrl?: string;
  accountButtonSelectors: string;
  logoutButtonSelectors: string;
  cartButtonSelectors: string;
  loginButtonSelectors: string;
  display: DisplayOptions;
  termsAndConditionsLink: string;
  language: string;
  locale: string | null;
  translations: Translations;
  showTranslations: boolean;
  checkoutCustomElements: CheckoutElementConfig[];
  paymentMethodsOrder: PaymentMethodName[];
  saveToAddressBookDefault: boolean;
  productLink: string;
  customAccountDetails: {
    title: string;
    value: string | number;
    displayText?: string;
    type?: CustomAccountDetailLinkType;
  }[];
  onCheckoutValidation(
    cart: Cart,
    cartUiState: CartUIState,
  ): Promise<{ message: string }[] | null>;
  onCartUpdate(cart: Cart, results: CartResults[]): Promise<void>;
  onCartLoad(cart: Cart): Promise<void>;
  preCartUpdateListener(input: Partial<UpdateCart>): Promise<Partial<UpdateCart>>;
  onReady?(spark: Spark): Promise<void>;
  onLoad?(spark: Spark): Promise<void>;
  onLogout?(): Promise<void>;
  shopify?: {
    useAppProxy?: boolean;
  };
  bigcommerce?: {
    appClientId?: string;
  };
  auth: {
    user?: string;
    token?: string;
  };
  authLogoutUri: string | null;
  analytics?: AnalyticsOptions;
  igniteCheckoutContext?: Record<string, unknown>;
};
```

The function-valued options (`onReady`, `onCartUpdate` and the rest) are on the [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md) page.

## Site and platform

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `siteId` | `string` | – | Your site ID. Required. |
| `sparkDomain` | `"app.sparklayer.io" \| "test.app.sparklayer.io"` | `"app.sparklayer.io"` | The domain of the SparkLayer API. |
| `platform` | `"base" \| "bigcommerce" \| "shopify" \| "wix" \| "woocommerce" \| "magento"` | `"base"` | Sets the default options for your ecommerce platform. |
| `rootUrl` | `string` | `""` | The root URL used to prefix any URLs SparkLayer creates, generally used for i18n. A trailing `/` is removed. |
| `wordpressSiteUrl?` | `string` | – | The URL of the WordPress site when using the WooCommerce platform. |
| `shopify?` | `{ useAppProxy?: boolean }` | – | Shopify-specific options. |
| `shopify.useAppProxy?` | `boolean` | `true` on Shopify | Send API requests through the Shopify app proxy (`/tools/sparklayer` under `rootUrl`) instead of calling `sparkDomain` directly. |
| `bigcommerce?` | `{ appClientId?: string }` | – | BigCommerce-specific options. |
| `bigcommerce.appClientId?` | `string` | – | Your BigCommerce app client ID. |

## Links and redirects

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `accountRedirect` | `{ urlRegex?: RegExp; goTo?: string }` | – | When a logged-in user visits a path matching `urlRegex`, they're sent to `goTo` with the account drawer open. |
| `accountRedirect.urlRegex?` | `RegExp` | – | Pattern matched against the current path. |
| `accountRedirect.goTo?` | `string` | – | Path (relative to `rootUrl`) to redirect to. |
| `cartRedirect` | `{ urlRegex?: RegExp; goTo?: string }` | – | When a logged-in user visits a path matching `urlRegex`, they're sent to `goTo` with the cart drawer open. |
| `cartRedirect.urlRegex?` | `RegExp` | – | Pattern matched against the current path. |
| `cartRedirect.goTo?` | `string` | – | Path (relative to `rootUrl`) to redirect to. |
| `termsAndConditionsLink` | `string` | `/terms-of-service` (`/policies/terms-of-service` on Shopify) | Link to your terms and conditions. |
| `productLink` | `string` | `/:product-slug:` (`/products/:product-slug:` on Shopify, `/product-page/:product-slug:` on Wix) | The link to a product page, where `:product-slug:` is replaced with the product's slug. |

## Button selectors

SparkLayer attaches to elements matching these CSS selectors. The defaults below are for the `base` platform; BigCommerce, Magento, Shopify, Wix and WooCommerce set their own.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `accountButtonSelectors` | `string` | `[href*="/account"]:not([href$="/account/logout"]), [data-spark-link=account]` | Selectors for the account button. |
| `logoutButtonSelectors` | `string` | `[href$="/account/logout"], [data-spark-link=logout]` | Selectors for the logout button. |
| `cartButtonSelectors` | `string` | `[href$="/cart"], [data-spark-link=cart]` | Selectors for the cart button. |
| `loginButtonSelectors` | `string` | `[href$="/spark-b2b-login"], [data-spark-link=login]` | Selectors for the login button. |

If your site re-renders these buttons, they can lose SparkLayer's click handlers. Open the drawer from your own click handler instead, with [`openDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer).

## Display, language and translations

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `display` | [`DisplayOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#displayoptions) | See [`DisplayOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#displayoptions) | Display options for SparkLayer. |
| `language` | `string` | `"en"` | The language SparkLayer uses. |
| `locale` | `string \| null` | The browser's locale | The locale used for formatting: currently only dates. Examples: `en-GB`, `en-US`, `de-DE`. An empty or unsupported value falls back to the browser locale with a console warning. |
| `translations` | [`Translations`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#translations) | – | Override internal translations, keyed by language code. |
| `showTranslations` | `boolean` | `false` | Shows translation keys instead of text, which helps you debug translations. |

## Checkout and account

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `checkoutCustomElements` | [`CheckoutElementConfig`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#checkoutelementconfig)`[]` | – | Elements to display in checkout: SparkLayer's standard fields (by `id`) or your own custom ones. |
| `paymentMethodsOrder` | [`PaymentMethodName`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#paymentmethodname)`[]` | – | The order in which payment methods are shown. |
| `saveToAddressBookDefault` | `boolean` | `true` | Whether new addresses are saved to the user's address book by default. |
| `customAccountDetails` | `{ title: string; value: string \| number; displayText?: string; type?: CustomAccountDetailLinkType }[]` | – | Title and value pairs to show on a customer's My Details panel. Set `type` (see [`CustomAccountDetailLinkType`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#customaccountdetaillinktype)) to format the value as a link. |
| `igniteCheckoutContext?` | `Record<string, unknown>` | – | A JSON object of checkout context data to pass to Ignite. |

To validate the cart before checkout, use the [`onCheckoutValidation`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncheckoutvalidation) hook.

## Authentication and analytics

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `auth` | `{ user?: string; token?: string }` | – | Credentials for SparkLayer auth. |
| `auth.user?` | `string` | – | The user to authenticate as. |
| `auth.token?` | `string` | – | The token for that user. |
| `authLogoutUri` | `string \| null` | `null` | The logout URI for SparkLayer auth. After logging out, SparkLayer redirects to this path under `rootUrl`. |
| `analytics?` | [`AnalyticsOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#analyticsoptions) | – | Analytics providers and events. See [Event tracking for analytics](https://docs.sparklayer.io/developers/frontend/technical-information.md#event-tracking-for-analytics-google-analytics-ga4). |

## Next steps

- [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md): Where to set your options so they're in place before the Core Script loads.
- [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md): The functions on sparkOptions that SparkLayer calls at key moments.
- [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md): Pass these options to window\.initSpark() on a headless storefront.