# Injection Methods API

Methods for injecting SDK components into your page.

## injectProductElement()

Inject one or more product displays.

### Signature

```typescript
injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>
```

### Parameters

```typescript
interface IInjectProductElement {
  containerId: string;  // ID of container element
  identifier: string;   // Product Identifier
}
```

### Example

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

### Returns

Array of injected component objects.

---

## injectAddressElement()

Inject standalone address component.

### Signature

```typescript
injectAddressElement(
  containerId: string,
  options?: IAddressOptions
): Promise<IInjectedComponent | null>
```

### Example

```javascript
await client.injectAddressElement('address-container', {
  showLabel: true
});

// Listen for address changes via the published event (dispatched on window)
window.addEventListener('lce:actions.address_updated', (event) => {
  console.log('Address set:', event.detail.data);
});
```

---

## injectCartElement()

Inject standalone cart (rarely needed - cart drawer is automatic).

### Signature

```typescript
injectCartElement(containerId: string): Promise<IInjectedComponent | null>
```

### Example

```javascript
await client.injectCartElement('cart-container');
```

---

## injectCheckoutElement()

Inject hosted checkout page.

### Signature

```typescript
injectCheckoutElement(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>
```

### Parameters

```typescript
interface IInjectCheckoutParams {
  containerId: string;
  checkoutId?: string;   // Optional checkout token to load
  hideHeader?: boolean;  // Hide checkout header
}
```

### Example

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

---

## injectProductList()

Inject product catalog/listing.

### Signature

```typescript
injectProductList(params: IInjectProductListParams): Promise<void>
```

### Parameters

```typescript
interface IInjectProductListParams {
  containerId: string;
  slug: string;              // Product list slug identifier
  rows?: number;             // Default: 4
  columns?: number;          // Default: 4
  filters?: ProductListFilterType[];
  productUrl?: PLCProductUrl;  // string template OR Record<identifier, url> map
}

// String template: replace {upc} or {grouping} per product.
// Map: keys are product identifiers (UPC or salsifyGrouping ID); UPC checked first.
type PLCProductUrl = string | Record<string, string>;
```

### Example — string template

```javascript
await client.injectProductList({
  containerId: 'products',
  slug: 'best-sellers',
  rows: 4,
  columns: 3,
  filters: ['price', 'brands', 'categories'],
  productUrl: '/product/{grouping}'
});
```

> The `filters` array also acts as the whitelist for **URL query param filtering** —
> the product list reads `?brands=...&price=...` etc. from `window.location.search`
> on first mount and applies them. See
> [URL Query Param Filters](../guides/product-list-component.md#url-query-param-filters).

### Example — URL map (partner-owned dedicated PDPs)

Use this form when each product has a hand-curated URL that can't be derived
from a single `{upc}` or `{grouping}` token. See the
[Product List guide](../guides/product-list-component.md#product-url-map) for
the equivalent declarative `<script type="application/json">` pattern.

```javascript
await client.injectProductList({
  containerId: 'products',
  slug: 'best-sellers',
  productUrl: {
    'GROUPING-33277': '/wines/macallan-12-special-edition',
    '00832889005513': '/spirits/cabernet-2018-club-only',
  },
});
```

---

## injectProductListSearch()

Inject product search box.

### Signature

```typescript
injectProductListSearch(params: IInjectProductListSearchParams): Promise<void>
```

### Parameters

```typescript
interface IInjectProductListSearchParams {
  containerId: string;
  slug: string;  // Product list slug identifier
  filters?: ProductListFilterType[];
}
```

### Example

```javascript
await client.injectProductListSearch({
  containerId: 'search-box',
  slug: 'best-sellers'
});
```

---

## injectProductListFilters()

Inject product filter panel.

### Signature

```typescript
injectProductListFilters(params: IInjectProductListFiltersParams): Promise<void>
```

### Parameters

```typescript
interface IInjectProductListFiltersParams {
  containerId: string;
  slug: string;  // Product list slug identifier
  filters?: ProductListFilterType[];
}
```

### Example

```javascript
await client.injectProductListFilters({
  containerId: 'filters',
  slug: 'best-sellers',
  filters: ['price', 'brands', 'fulfillment']
});
```

---

## Component Management

### getInjectedComponents()

Retrieve all injected components.

```typescript
getInjectedComponents(): Map<string, IInjectedComponent>
```

```javascript
const components = client.getInjectedComponents();

// Get specific component
const product = components.get('product-1');

// Rerender component
product.rerender();

// Get container element
const container = product.getElement();

// Get component type
const type = product.getType(); // 'product'
```

### IInjectedComponent Interface

```typescript
interface IInjectedComponent {
  getType(): ComponentType;
  getElement(): HTMLElement;
  rerender(): void;
  destroy(): void;
}
```

| Method | Returns | Description |
|--------|---------|-------------|
| `getType()` | `ComponentType` | Returns the type of the injected component |
| `getElement()` | `HTMLElement` | Returns the container element where the component is injected |
| `rerender()` | `void` | Re-renders the component with the latest data and configurations |
| `destroy()` | `void` | Removes the component from the DOM and cleans up internal tracking |

## See Also

- [Client API](./client.md)
- [Component Guides](../guides/)