# 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](/web-sdk/components/invoice-detail.md)               | Show detailed invoice information |
| [Payment Method Select](/web-sdk/components/payment-method-select.md) | List and select payment methods   |
| [Add Payment Method](/web-sdk/components/add-payment-method.md)       | Add new card or bank account      |
| [Payment Confirmation](/web-sdk/components/payment-confirmation.md)   | Review and confirm payment        |
| [Payment Result](/web-sdk/components/payment-result.md)               | 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.


---

# Agent Instructions: 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.alternativepayments.io/web-sdk/components.md?ask=<question>
```

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.