# UI Helpers API

UI helper methods for creating cart buttons and displaying cart information.

## ui.cartButton()

Create a cart button in a specific container.

### Signature

```typescript
cartButton(containerId: string, showItemsCount?: boolean): void
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `containerId` | string | Yes | ID of container element |
| `showItemsCount` | boolean | No | Show item count badge (default: false) |

### Example

```javascript
// Simple cart button
window.LiquidCommerce.elements.ui.cartButton('header-cart');

// Cart button with item count badge
window.LiquidCommerce.elements.ui.cartButton('header-cart', true);
```

---

## ui.floatingCartButton()

Create a floating cart button (bottom-right corner).

### Signature

```typescript
floatingCartButton(showItemsCount?: boolean): void
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `showItemsCount` | boolean | No | Show item count badge (default: false) |

### Example

```javascript
// Floating button without badge
window.LiquidCommerce.elements.ui.floatingCartButton();

// Floating button with badge
window.LiquidCommerce.elements.ui.floatingCartButton(true);
```

---

## ui.cartSubtotal()

Display cart subtotal in an element.

### Signature

```typescript
cartSubtotal(elementId: string): void
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `elementId` | string | Yes | ID of element to update |

### Example

```html
<div>Total: <span id="cart-total"></span></div>
```

```javascript
window.LiquidCommerce.elements.ui.cartSubtotal('cart-total');
// Element now shows: "$49.99"
// Updates automatically when cart changes
```

---

## ui.cartItemsCount()

Display number of items in cart.

### Signature

```typescript
cartItemsCount(elementId: string, options?: { hideZero: boolean }): void
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `elementId` | string | Yes | ID of element to update |
| `options.hideZero` | boolean | No | Hide when cart is empty (default: true) |

### Example

```html
<div>Cart (<span id="items-count"></span>)</div>
```

```javascript
// Hide when cart is empty
window.LiquidCommerce.elements.ui.cartItemsCount('items-count', { hideZero: true });

// Always show count (even "0")
window.LiquidCommerce.elements.ui.cartItemsCount('items-count', { hideZero: false });
```

## Use Cases

### Header Cart Button

```html
<header>
  <nav>
    <a href="/">Home</a>
    <a href="/products">Products</a>
    <div id="cart-btn"></div>
  </nav>
</header>

<script>
window.addEventListener('lce:actions.client_ready', () => {
  window.LiquidCommerce.elements.ui.cartButton('cart-btn', true);
});
</script>
```

### Cart Summary Widget

```html
<aside class="cart-summary">
  <h3>Your Cart</h3>
  <p>Items: <span id="item-count"></span></p>
  <p>Total: <span id="cart-total"></span></p>
</aside>

<script>
window.addEventListener('lce:actions.client_ready', () => {
  window.LiquidCommerce.elements.ui.cartItemsCount('item-count');
  window.LiquidCommerce.elements.ui.cartSubtotal('cart-total');
});
</script>
```

### Floating Cart for Mobile

```javascript
// Show floating button only on mobile
if (window.innerWidth < 768) {
  window.LiquidCommerce.elements.ui.floatingCartButton(true);
}
```

## Styling

Cart buttons and UI elements can be styled with CSS:

```css
/* Cart button container */
.lce-cart-desktop-button-container {
  /* Your styles */
}

/* Cart items count */
.lce-cart-items-count {
  font-weight: bold;
  color: #007bff;
}

/* When cart is empty */
.lce-cart-items-count.no-items {
  opacity: 0.5;
}

/* Cart subtotal */
.lce-cart-subtotal {
  font-size: 1.2em;
  font-weight: bold;
}
```

## See Also

- [Cart Component Guide](../guides/cart-component.md)
- [Cart Actions](./actions/cart-actions.md)