Overview

A lightweight, developer-facing guide to integrate LiquidCommerce Elements SDK into your site or app.

What it is

Elements SDK is a Web Components-based e-commerce SDK that embeds product, cart, address, and checkout experiences into any website. It works with plain HTML or any framework and exposes a simple client + actions API.

Core components

• Product: product detail display + add to cart

• Cart: slide-out cart drawer + promo codes

• Checkout: full checkout flow (drawer or hosted page)

• Address: delivery location and availability

Quick start (CDN)

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="production"
  data-container-1="product"
  data-product-1="00619947000020"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

<div id="product"></div>

Quick start (NPM)

npm install @liquidcommerce/elements-sdk

import { Elements } from '@liquidcommerce/elements-sdk';

const client = await Elements('YOUR_API_KEY', { env: 'production' });
await client.injectProductElement([
  { containerId: 'product', identifier: '00619947000020' }
]);

Initialization modes

• Declarative (CDN): data attributes on the script tag, auto-initialized

• Programmatic (NPM or CDN): call Elements(...) and inject components

The client is available globally as window.elements as soon as the SDK is ready.

Quick Start Guide (auto-setup)

Most partners use the auto-setup approach because it is the fastest to implement. It supports rich configuration via data attributes, including product injection, cart buttons, checkout, query param handling, and more.

See Quick Start Guide for the complete list of supported attributes and combinations.

Configuration basics

const client = await Elements('YOUR_API_KEY', {
  env: 'production', // development | staging | production
});

Client (exposed methods)

After initialization, the client exposes three main groups: injection methods, actions, and ui helpers, plus component management.

Injection methods

Use these to mount SDK components into your DOM. Each method is shown with a minimal example.

injectProductElement(params[])

Inject one or more product components by container ID + product identifier.

await client.injectProductElement([
  { containerId: 'product-1', identifier: '00619947000020' },
  { containerId: 'product-2', identifier: '08504405135' }
]);

injectAddressElement(containerId, options?)

Inject a standalone address component (optional callbacks like onAddressSet).

await client.injectAddressElement('address', {
  onAddressSet: (address) => console.log(address)
});

injectCartElement(containerId)

Inject a standalone cart component (rare; cart drawer is automatic).

await client.injectCartElement('cart');

injectCheckoutElement(params)

Inject a hosted checkout into a container.

await client.injectCheckoutElement({
  containerId: 'checkout',
  checkoutId: 'checkout_abc123',
  hideHeader: false
});

Actions (client.actions.*)

Actions are programmatic controls for state changes and flows. The full list with details is in Actions.

// Example: add to cart and open cart
await window.elements.actions.cart.addProduct([
  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
], true);

UI helpers (client.ui.*)

Helpers for common cart UI elements that stay in sync automatically.

ui.cartButton(containerId, showItemsCount?)

Renders a cart button in a container.

window.elements.ui.cartButton('header-cart', true);

ui.floatingCartButton(showItemsCount?)

Renders a floating cart button (bottom-right).

window.elements.ui.floatingCartButton(true);

ui.cartSubtotal(elementId)

Keeps a DOM element updated with cart subtotal.

<span id="cart-total"></span>

window.elements.ui.cartSubtotal('cart-total');

ui.cartItemsCount(elementId, { hideZero })

Keeps a DOM element updated with item count.

<span id="items-count"></span>

window.elements.ui.cartItemsCount('items-count', { hideZero: true });

Component management

You can inspect and re-render injected components.

• getInjectedComponents() Returns a map of injected components keyed by container ID.

const components = client.getInjectedComponents();
const productComponent = components.get('product-1');

productComponent.getType();    // 'product'
productComponent.getElement(); // underlying element
productComponent.rerender();   // force re-render

Recommended flow

1. Initialize the client

2. Inject product(s)

3. Let the cart drawer handle checkout by default

4. Use actions + events to track analytics and UI updates

For details, see the component pages: Product, Cart, Checkout, Address, Actions, Events.