> For the complete documentation index, see [llms.txt](https://docs.liquidcommerce.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.liquidcommerce.cloud/elements-v2/overview.md).
# 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)
To obtain your API key, navigate to the Elements page in your Partner App account.
```html
```
## Quick start (NPM)
```bash
npm install @liquidcommerce/elements-sdk
```
```js
import { Elements } from '@liquidcommerce/elements-sdk';
// To obtain your API key, navigate to the Elements page in your Partner App account.
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.LiquidCommerce.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](/elements-v2/quick-start-guide.md) for the complete list of supported attributes and combinations.
## Configuration basics
```js
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.
```js
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`).
```js
await client.injectAddressElement('address', {
onAddressSet: (address) => console.log(address)
});
```
#### `injectCartElement(containerId)`
Inject a standalone cart component (rare; cart drawer is automatic).
```js
await client.injectCartElement('cart');
```
#### `injectCheckoutElement(params)`
Inject a hosted checkout into a container.
```js
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](broken://pages/0a41d310771b69fd73c3c3a3887348f1d54bb860).
```js
// Example: add to cart and open cart
await window.LiquidCommerce.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.
```js
window.LiquidCommerce.elements.ui.cartButton('header-cart', true);
```
#### `ui.floatingCartButton(showItemsCount?)`
Renders a floating cart button (bottom-right).
```js
window.LiquidCommerce.elements.ui.floatingCartButton(true);
```
#### `ui.cartSubtotal(elementId)`
Keeps a DOM element updated with cart subtotal.
```html
```
```js
window.LiquidCommerce.elements.ui.cartSubtotal('cart-total');
```
#### `ui.cartItemsCount(elementId, { hideZero })`
Keeps a DOM element updated with item count.
```html
```
```js
window.LiquidCommerce.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.
```js
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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.liquidcommerce.cloud/elements-v2/overview.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.