# Components

## Overview

The SDK provides individual components that can be used to build custom payment experiences. Access them via `client.components.*`.

***

## Available Components

| Component                                                                                             | Description                       |
| ----------------------------------------------------------------------------------------------------- | --------------------------------- |
| [Invoice Detail](https://docs.alternativepayments.io/web-sdk/components/invoice-detail)               | Show detailed invoice information |
| [Payment Method Select](https://docs.alternativepayments.io/web-sdk/components/payment-method-select) | List and select payment methods   |
| [Add Payment Method](https://docs.alternativepayments.io/web-sdk/components/add-payment-method)       | Add new card or bank account      |
| [Payment Confirmation](https://docs.alternativepayments.io/web-sdk/components/payment-confirmation)   | Review and confirm payment        |
| [Payment Result](https://docs.alternativepayments.io/web-sdk/components/payment-result)               | Display payment outcome           |

***

## Using Components

All components share a common pattern:

```typescript
// 1. Initialize the client
const client = new AlternativeClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

// 2. Create a component
const component = client.components.invoiceList({
  containerId: 'my-container',
  customerId: 'cus_xxx',
  onSelect: (invoice) => {
    console.log('Selected:', invoice);
  },
});

// 3. Later: cleanup
component.unmount();
```

***

## Common Configuration

All components accept these base properties:

| Property      | Type          | Required | Description                             |
| ------------- | ------------- | -------- | --------------------------------------- |
| `containerId` | `string`      | Yes      | ID of the HTML element to mount into    |
| `theme`       | `ThemeConfig` | No       | Custom theme (overrides client default) |

***

## Component Instance

Each component returns a `ComponentInstance` with these methods:

```typescript
interface ComponentInstance {
  mount(): void;      // Mount to DOM (auto-called on creation)
  unmount(): void;    // Remove from DOM
  refresh(): Promise<void>;  // Refresh data
}
```

***

## Building Custom Flows

Compose components to create custom payment experiences:

```typescript
const client = new AlternativeClient({ ... });

let selectedPaymentMethod: PaymentMethod | null = null;
const invoiceId = 'inv_xxx';

// Step 1: Show payment method selection
const paymentSelect = client.components.paymentMethodSelect({
  containerId: 'container',
  customerId: 'cus_xxx',
  onSelect: (pm) => {
    selectedPaymentMethod = pm;
    paymentSelect.unmount();
    showConfirmation();
  },
  onAddNew: () => {
    paymentSelect.unmount();
    showAddPaymentMethod();
  },
});

// Step 2: Confirm and process
function showConfirmation() {
  const confirmation = client.components.paymentConfirmation({
    containerId: 'container',
    invoiceId: invoiceId,
    paymentMethodId: selectedPaymentMethod!.id,
    customerId: 'cus_xxx',
    onPaymentSuccess: (payment) => {
      confirmation.unmount();
      showResult('success', payment);
    },
    onPaymentError: (error) => {
      confirmation.unmount();
      showResult('error', undefined, error);
    },
  });
}
```

***

## Next Steps

Explore individual component documentation for detailed configuration options and examples.