@blocklet/payment-react/docs/components-ui-form-elements-currency-selector.md

Reusable react components for payment kit v2

# CurrencySelector

The `CurrencySelector` component provides a user-friendly interface for selecting a payment currency from a list of available options. It displays each currency with its logo, symbol, and associated payment method, making it easy for users to make a choice. This component is typically used within a larger payment or checkout form.

## Props

| Prop         | Type                                                     | Description                                                                                                       | Required |
| :----------- | :------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | :------- |
| `value`      | `string`                                                 | The ID of the currently selected currency. This should be managed by the parent component's state.              | Yes      |
| `currencies` | `TPaymentCurrency[]`                                     | An array of available currency objects to display as selectable options.                                          | Yes      |
| `onChange`   | `(currencyId: string, methodId?: string) => void`        | Callback function that is executed when a user selects a currency. It receives the new currency ID and the optional associated payment method ID. | Yes      |

### TPaymentCurrency Type

The `currencies` prop expects an array of objects with the following structure:

```typescript TPaymentCurrency icon=mdi:code-json
export type TPaymentCurrency = {
  id: string;       // Unique identifier for the currency option
  logo: string;     // URL for the currency/method logo
  name: string;     // Display name for the currency
  symbol: string;   // Currency symbol (e.g., '$', '€')
  method: {         // Associated payment method
    id: string;
    name: string;
  };
};
```

## Usage Example

Here is a basic example of how to implement the `CurrencySelector` component. You need to manage the selected currency's state in the parent component and provide a list of available currencies.

Note that `@blocklet/payment-react` components are designed to work within a `PaymentProvider`, which supplies the necessary theme and context. Ensure your component is wrapped accordingly.

```jsx MyCurrencySelectorComponent.tsx icon=logos:react
import React, { useState } from 'react';
import { PaymentProvider } from '@blocklet/payment-react';
import { CurrencySelector } from '@blocklet/payment-react/components';
import type { TPaymentCurrency } from '@blocklet/payment-types';
import { useSessionContext } from '@/hooks/session-context'; // Adjust this import path to your project structure

// Mock data for demonstration purposes
const mockCurrencies: TPaymentCurrency[] = [
  {
    id: 'usd_xxxxxx',
    logo: 'https://path-to-your/usd-logo.png',
    name: 'US Dollar',
    symbol: 'USD',
    method: {
      id: 'stripe_yyyyy',
      name: 'Stripe',
    },
  },
  {
    id: 'eth_zzzzzz',
    logo: 'https://path-to-your/eth-logo.png',
    name: 'Ethereum',
    symbol: 'ETH',
    method: {
      id: 'crypto_aaaaa',
      name: 'Crypto Payment',
    },
  },
];

function MyCurrencySelectorComponent() {
  const [selectedCurrency, setSelectedCurrency] = useState<string>(mockCurrencies[0].id);

  const handleCurrencyChange = (currencyId: string, methodId?: string) => {
    console.log(`Selected currency: ${currencyId}, Method: ${methodId}`);
    setSelectedCurrency(currencyId);
  };

  return (
    <div>
      <h3>Select a Currency</h3>
      <CurrencySelector
        value={selectedCurrency}
        currencies={mockCurrencies}
        onChange={handleCurrencyChange}
      />
    </div>
  );
}

// Your App's entry point
export default function App() {
  const { session, connectApi } = useSessionContext();

  if (!session || !connectApi) {
    return <div>Loading...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <MyCurrencySelectorComponent />
    </PaymentProvider>
  );
}
```

In this example:
1.  We define a `mockCurrencies` array that follows the `TPaymentCurrency` structure.
2.  The `MyCurrencySelectorComponent` uses the `useState` hook to keep track of the `selectedCurrency`.
3.  The `handleCurrencyChange` function updates the state when a new currency is selected and logs the new values.
4.  The `CurrencySelector` is a controlled component, with its `value` and `onChange` props managed by the parent's state.
5.  The entire component is wrapped in `PaymentProvider` to ensure proper rendering and access to the Material-UI theme used for styling.