# Configuration Reference

Complete reference for all configuration options available in the Elements SDK.

## Client Configuration

### ILiquidCommerceElementsConfig

Top-level configuration passed to `Elements()` or `ElementsBuilder()`.

```typescript
interface ILiquidCommerceElementsConfig {
  env?: ElementsEnv;
  promoTicker?: IPromoTicker[];
  customTheme?: IClientCustomThemeConfig;
  debugMode?: DebugMode;
  checkout?: ILiquidCommerceElementsCheckoutConfig;
  proxy?: IElementsProxyConfig;
  development?: ILiquidCommerceElementsDevelopmentConfig;
}
```

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `env` | `'development' \| 'staging' \| 'production'` | No | API environment |
| `promoTicker` | `IPromoTicker[]` | No | Promotional ticker configurations |
| `customTheme` | `IClientCustomThemeConfig` | No | Theme overrides for all components |
| `debugMode` | `'none' \| 'console' \| 'panel'` | No | Debug output mode |
| `checkout` | `ILiquidCommerceElementsCheckoutConfig` | No | Checkout behavior settings |
| `proxy` | `IElementsProxyConfig` | No | Proxy configuration for API requests |
| `development` | `ILiquidCommerceElementsDevelopmentConfig` | No | Development/testing options |

---

## Theme Configuration

### IClientCustomThemeConfig

Override default theme settings for any component.

```typescript
interface IClientCustomThemeConfig {
  global?: UpdateComponentGlobalConfigs;
  product?: UpdateProductComponent;
  address?: UpdateAddressComponent;
  cart?: UpdateCartComponent;
  checkout?: UpdateCheckoutComponent;
  productList?: UpdateProductListComponent;
}
```

All theme properties are deeply partial -- you only need to specify the values you want to override.

---

### Global Theme

#### IGlobalTheme

```typescript
interface IGlobalTheme {
  buttonCornerRadius: string;
  cardCornerRadius: string;
  headingFont: IFontFamily;
  paragraphFont: IFontFamily;
  primaryColor: string;
  accentColor: string;
  defaultTextColor: string;
  selectedTextColor: string;
  linkTextColor: string;
  errorColor: string;
  warningColor: string;
  successColor: string;
  drawerBackgroundColor: string;
}
```

| Property | Type | Description |
|----------|------|-------------|
| `buttonCornerRadius` | `string` | CSS border-radius for buttons (e.g., `'8px'`) |
| `cardCornerRadius` | `string` | CSS border-radius for cards |
| `headingFont` | `IFontFamily` | Font family and weights for headings |
| `paragraphFont` | `IFontFamily` | Font family and weights for body text |
| `primaryColor` | `string` | Primary brand color (buttons, links, highlights) |
| `accentColor` | `string` | Secondary accent color |
| `defaultTextColor` | `string` | Default text color |
| `selectedTextColor` | `string` | Text color for selected/active elements |
| `linkTextColor` | `string` | Color for links |
| `errorColor` | `string` | Color for error states |
| `warningColor` | `string` | Color for warning states |
| `successColor` | `string` | Color for success states |
| `drawerBackgroundColor` | `string` | Background color for drawer components |

#### IFontFamily

```typescript
interface IFontFamily {
  name: string;      // Google Font name (e.g., 'Inter')
  weights: number[]; // Font weights to load (e.g., [400, 500, 700])
}
```

#### IGlobalLayout

```typescript
interface IGlobalLayout {
  enablePersonalization: boolean;
  personalizationText: string;
  personalizationCardStyle: 'outlined' | 'filled';
  allowPromoCodes: boolean;
  inputFieldStyle: 'outlined' | 'filled';
  showPoweredBy: boolean;
  poweredByMode: 'light' | 'dark';
}
```

| Property | Type | Description |
|----------|------|-------------|
| `enablePersonalization` | `boolean` | Enable engraving/personalization features |
| `personalizationText` | `string` | Label text for personalization option |
| `personalizationCardStyle` | `'outlined' \| 'filled'` | Visual style for personalization cards |
| `allowPromoCodes` | `boolean` | Show promo code inputs in cart/checkout |
| `inputFieldStyle` | `'outlined' \| 'filled'` | Visual style for input fields |
| `showPoweredBy` | `boolean` | Show "Powered by LiquidCommerce" badge |
| `poweredByMode` | `'light' \| 'dark'` | Color mode for the powered-by badge |

**Example:**

```javascript
customTheme: {
  global: {
    theme: {
      primaryColor: '#007bff',
      buttonCornerRadius: '8px',
      headingFont: { name: 'Inter', weights: [400, 600, 700] }
    },
    layout: {
      allowPromoCodes: true,
      inputFieldStyle: 'outlined'
    }
  }
}
```

---

### Product Theme

#### IProductComponent

```typescript
interface IProductComponent {
  theme: IProductTheme;
  layout: IProductLayout;
}
```

#### IProductTheme

```typescript
interface IProductTheme {
  backgroundColor: string;
}
```

#### IProductLayout

```typescript
interface IProductLayout {
  showImages: boolean;
  showOnlyMainImage: boolean;
  showTitle: boolean;
  showDescription: boolean;
  showQuantityCounter: boolean;
  showOffHours: boolean;
  quantityCounterStyle: 'outlined' | 'ghost';
  fulfillmentDisplay: 'carousel' | 'popup';
  enableShippingFulfillment: boolean;
  enableOnDemandFulfillment: boolean;
  addToCartButtonText: string;
  addToCartButtonShowTotalPrice: boolean;
  buyNowButtonText: string;
  preSaleButtonText: string;
  prioritizeEngraving: boolean;
  noAvailabilityText: string;
}
```

| Property | Type | Description |
|----------|------|-------------|
| `showImages` | `boolean` | Show product image carousel |
| `showOnlyMainImage` | `boolean` | Show only the main product image (no carousel) |
| `showTitle` | `boolean` | Show product title |
| `showDescription` | `boolean` | Show product description |
| `showQuantityCounter` | `boolean` | Show quantity selector |
| `showOffHours` | `boolean` | Show off-hours messaging |
| `quantityCounterStyle` | `'outlined' \| 'ghost'` | Visual style for quantity counter |
| `fulfillmentDisplay` | `'carousel' \| 'popup'` | How to display fulfillment/retailer options |
| `enableShippingFulfillment` | `boolean` | Enable shipping fulfillment option |
| `enableOnDemandFulfillment` | `boolean` | Enable on-demand delivery option |
| `addToCartButtonText` | `string` | Custom text for add-to-cart button |
| `addToCartButtonShowTotalPrice` | `boolean` | Show total price on add-to-cart button |
| `buyNowButtonText` | `string` | Custom text for buy-now button |
| `preSaleButtonText` | `string` | Custom text for pre-sale button |
| `prioritizeEngraving` | `boolean` | Show engraving option before add-to-cart |
| `noAvailabilityText` | `string` | Text shown when product is unavailable |

**Example:**

```javascript
customTheme: {
  product: {
    layout: {
      fulfillmentDisplay: 'popup',
      addToCartButtonText: 'Add to Bag',
      showQuantityCounter: true
    }
  }
}
```

---

### Cart Theme

#### ICartComponent

```typescript
interface ICartComponent {
  theme: ICartTheme;
  layout: ICartLayout;
}
```

#### ICartTheme

```typescript
interface ICartTheme {
  backgroundColor: string;
}
```

#### ICartLayout

```typescript
interface ICartLayout {
  showQuantityCounter: boolean;
  quantityCounterStyle: 'outlined' | 'ghost';
  drawerHeaderText: string;
  goToCheckoutButtonText: string;
}
```

| Property | Type | Description |
|----------|------|-------------|
| `showQuantityCounter` | `boolean` | Show quantity counter in cart items |
| `quantityCounterStyle` | `'outlined' \| 'ghost'` | Visual style for quantity counter |
| `drawerHeaderText` | `string` | Header text for the cart drawer |
| `goToCheckoutButtonText` | `string` | Custom text for checkout button |

**Example:**

```javascript
customTheme: {
  cart: {
    theme: { backgroundColor: '#f8f9fa' },
    layout: {
      drawerHeaderText: 'Your Bag',
      goToCheckoutButtonText: 'Proceed to Checkout'
    }
  }
}
```

---

### Checkout Theme

#### ICheckoutComponent

```typescript
interface ICheckoutComponent {
  theme: ICheckoutTheme;
  layout: ICheckoutLayout;
}
```

#### ICheckoutTheme

```typescript
interface ICheckoutTheme {
  backgroundColor: string;
}
```

#### ICheckoutLayout

```typescript
interface ICheckoutLayout {
  emailOptIn: ICheckoutMarketingOptIn;
  smsOptIn: ICheckoutMarketingOptIn;
  allowGiftCards: boolean;
  legalMessage: ICheckoutLegalMessage;
  continueShoppingUrl: string;
  exitUrl: string;
  thankYouButtonText: string;
  drawerHeaderText: string;
  placeOrderButtonText: string;
  checkoutCompleted: ICheckoutCompleted;
}
```

| Property | Type | Description |
|----------|------|-------------|
| `emailOptIn` | `ICheckoutMarketingOptIn` | Email marketing opt-in configuration |
| `smsOptIn` | `ICheckoutMarketingOptIn` | SMS marketing opt-in configuration |
| `allowGiftCards` | `boolean` | Enable gift card payment option |
| `legalMessage` | `ICheckoutLegalMessage` | Legal/terms message configuration |
| `continueShoppingUrl` | `string` | URL for "Continue Shopping" link |
| `exitUrl` | `string` | URL for exit/back navigation |
| `thankYouButtonText` | `string` | Button text on order confirmation page |
| `drawerHeaderText` | `string` | Header text for checkout drawer |
| `placeOrderButtonText` | `string` | Custom text for place order button |
| `checkoutCompleted` | `ICheckoutCompleted` | Order confirmation page customization |

#### ICheckoutMarketingOptIn

```typescript
interface ICheckoutMarketingOptIn {
  show: boolean;     // Show the opt-in checkbox
  checked: boolean;  // Default checked state
  text: string;      // Label text (supports rich HTML)
}
```

#### ICheckoutLegalMessage

```typescript
interface ICheckoutLegalMessage {
  show: boolean;  // Show the legal message
  text: string;   // Message content (supports rich HTML)
}
```

#### ICheckoutCompleted

```typescript
interface ICheckoutCompleted {
  customLogo: string;        // URL to custom logo image
  customText: string | null; // Custom confirmation text
}
```

**Example:**

```javascript
customTheme: {
  checkout: {
    layout: {
      placeOrderButtonText: 'Complete Purchase',
      emailOptIn: { show: true, checked: false, text: 'Subscribe to our newsletter' },
      legalMessage: { show: true, text: 'By placing this order, you agree to our <a href="/terms">Terms</a>.' }
    }
  }
}
```

---

### Address Theme

#### IAddressComponent

```typescript
interface IAddressComponent {
  theme: IAddressTheme;
}
```

#### IAddressTheme

```typescript
interface IAddressTheme {
  backgroundColor: string;
}
```

---

### Product List Theme

#### IProductListComponent

```typescript
interface IProductListComponent {
  theme: IProductListTheme;
  layout: IProductListLayout;
}
```

Product list theme updates use a special structure where lists are keyed by slug:

```typescript
interface UpdateProductListComponent {
  theme?: { backgroundColor?: string };
  layout?: {
    lists?: Record<string, DeepPartial<IPLCList>>;
  };
}
```

**Example:**

```javascript
customTheme: {
  productList: {
    theme: { backgroundColor: '#ffffff' },
    layout: {
      lists: {
        'best-sellers': {
          productCard: {
            style: 'card',
            showPrice: true,
            enablePreCart: true
          }
        }
      }
    }
  }
}
```

---

## Promo Ticker Configuration

### IPromoTicker

```typescript
interface IPromoTicker {
  promoCode: string;    // Promo code to auto-apply
  text: string[];       // Array of messages to rotate
  separator: string;    // Separator between messages (e.g., '|')
  activeFrom: string;   // Start date in ISO 8601 UTC format
  activeUntil: string;  // End date in ISO 8601 UTC format
}
```

**Example:**

```javascript
promoTicker: [
  {
    promoCode: 'SUMMER20',
    text: ['20% Off Summer Sale', 'Free Shipping on $50+'],
    separator: '|',
    activeFrom: '2026-06-01T00:00:00Z',
    activeUntil: '2026-08-31T23:59:59Z'
  }
]
```

---

## Checkout Configuration

### ILiquidCommerceElementsCheckoutConfig

```typescript
interface ILiquidCommerceElementsCheckoutConfig {
  pageUrl?: string;  // URL with {token} placeholder
}
```

When `pageUrl` is set, the cart's checkout button redirects to this URL instead of opening the checkout drawer. Use `{token}` as a placeholder for the checkout session token.

**Example:**

```javascript
checkout: {
  pageUrl: 'https://yoursite.com/checkout?lce_checkout={token}'
}
```

---

## Proxy Configuration

### IElementsProxyConfig

```typescript
interface IElementsProxyConfig {
  baseUrl: string;
  headers?: Record<string, string>;
}
```

Route SDK API requests through your own server to avoid ad blockers.

See [Proxy Setup Guide](../integration/proxy-setup.md) for implementation details.

---

## Development Configuration

### ILiquidCommerceElementsDevelopmentConfig

```typescript
interface ILiquidCommerceElementsDevelopmentConfig {
  customApiUrl?: string;
  openShadowDom?: boolean;
}
```

| Property | Type | Description |
|----------|------|-------------|
| `customApiUrl` | `string` | Custom API URL for local or custom backend testing |
| `openShadowDom` | `boolean` | Disable Shadow DOM isolation for debugging (default: `false`) |

> To pre-select a payment method and skip the card form (in any environment), use [`actions.checkout.setSavedPaymentMethod`](./actions/checkout-actions.md#actionscheckoutsetsavedpaymentmethod) instead.

---

## See Also

- [Client API](./client.md) - Client initialization and usage
- [TypeScript Types](./typescript-types.md) - Complete type reference
- [Theming Guide](../guides/theming.md) - Theming best practices