> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Widgets

> Flutter widgets for the Flutter SDK reference for Crossmint wallets

The Flutter SDK provides optional UI widgets that can be imported from `crossmint_flutter_ui.dart`. These pull in Material Design dependencies — if you prefer a fully headless approach, use the [controllers](/sdk-reference/wallets/flutter/controllers) directly.

***

## CrossmintWalletStatusBuilder

Reactive widget that rebuilds whenever the wallet status or instance changes.

### Props

<ResponseField name="builder" type="Widget Function(BuildContext, CrossmintWalletContextData)" required>
  Builder called with the current wallet context data. Access status via `data.state.walletStatus` and wallet via `data.state.currentWallet`.
</ResponseField>

### Usage

```dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

CrossmintWalletStatusBuilder(
  builder: (context, data) {
    switch (data.state.walletStatus) {
      case CrossmintWalletStatus.inProgress:
        return const CircularProgressIndicator();
      case CrossmintWalletStatus.loaded:
        return Text('Address: ${data.state.currentWallet!.address}');
      default:
        return const Text('No wallet');
    }
  },
)
```

***

## CrossmintWalletConsumer

Provides access to the wallet context data from the widget tree.

### Usage

```dart theme={null}
CrossmintWalletConsumer(
  builder: (context, data) {
    return ElevatedButton(
      onPressed: () async {
        final wallet = data.state.currentWallet;
        final balances = await wallet?.balances();
        print('Balances: $balances');
      },
      child: const Text('Check Balances'),
    );
  },
)
```

***

## CrossmintWalletUiState (`data.state`)

The `state` exposed on `CrossmintWalletContextData` (the second argument of every builder). Fields and convenience getters:

| Field / getter        | Type                          | Description                                                                                                       |
| --------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `walletStatus`        | `CrossmintWalletStatus`       | `notLoaded`, `inProgress`, `loaded`, or `error`.                                                                  |
| `currentWallet`       | `CrossmintWallet?`            | The loaded wallet, or `null` before `walletStatus == loaded`.                                                     |
| `authState`           | `CrossmintAuthState`          | Sealed auth state — `CrossmintAuthInitializing`, `CrossmintAuthAuthenticated(user)`, or `CrossmintAuthLoggedOut`. |
| `isInitializing`      | `bool`                        | `true` while the SDK is still bootstrapping.                                                                      |
| `isLoadingWallet`     | `bool`                        | `true` while a `getWallet` / `createWallet` call is in flight.                                                    |
| `pendingOtpChallenge` | `CrossmintOtpChallenge?`      | Non-null when an OTP prompt is required.                                                                          |
| `hasWallet`           | `bool`                        | Convenience — `currentWallet != null`.                                                                            |
| `needsOtp`            | `bool`                        | Convenience — `pendingOtpChallenge != null`.                                                                      |
| `isAuthenticated`     | `bool`                        | `authState is CrossmintAuthAuthenticated`.                                                                        |
| `isLoggedOut`         | `bool`                        | `authState is CrossmintAuthLoggedOut`.                                                                            |
| `user`                | `CrossmintAuthenticatedUser?` | The authenticated user, or `null`.                                                                                |
| `error`               | `Object?`                     | Merges `initializationError` and `walletError`.                                                                   |
| `errorMessage`        | `String?`                     | Stringified `error`, or `null`.                                                                                   |

***

## CrossmintOtpSignerListener

Automatically listens for OTP challenges and shows the appropriate dialog. This is a Flutter advantage over React Native — OTP prompts are handled declaratively.

### Props

<ResponseField name="otpController" type="CrossmintWalletOtpController" required>
  The OTP controller from the wallet controller (e.g. `walletController.otp`).
</ResponseField>

<ResponseField name="child" type="Widget" required>
  The widget subtree.
</ResponseField>

<ResponseField name="enabled" type="bool">
  Whether the listener is active. Defaults to `true`.
</ResponseField>

<ResponseField name="barrierDismissible" type="bool">
  Whether the OTP dialog can be dismissed by tapping outside. Defaults to `false`.
</ResponseField>

### Usage

```dart theme={null}
CrossmintOtpSignerListener(
  otpController: walletController.otp,
  child: const WalletScreen(),
)
```

***

## CrossmintAuthForm

Pre-built authentication form with email OTP and OAuth buttons.

### Props

<ResponseField name="auth" type="CrossmintAuthClient" required>
  The auth client instance (e.g. `client.auth` or `data.requireAuth`).
</ResponseField>

<ResponseField name="providers" type="List<CrossmintOAuthProvider>">
  OAuth providers to display. Defaults to `[google, twitter]`.
</ResponseField>

<ResponseField name="showEmailSignIn" type="bool">
  Whether to show the email OTP form. Defaults to `true`.
</ResponseField>

<ResponseField name="onAuthenticated" type="VoidCallback">
  Called when authentication succeeds.
</ResponseField>

<ResponseField name="onError" type="void Function(Object)">
  Called when an error occurs during authentication.
</ResponseField>

### Usage

```dart theme={null}
CrossmintAuthForm(
  auth: client.auth,
  onAuthenticated: () {
    print('Logged in!');
  },
)
```

***

## CrossmintEmailSignIn

Email OTP sign-in form widget.

### Props

<ResponseField name="auth" type="CrossmintAuthClient" required>
  The auth client instance.
</ResponseField>

<ResponseField name="onAuthenticated" type="VoidCallback">
  Called when email OTP authentication succeeds.
</ResponseField>

<ResponseField name="onError" type="void Function(Object)">
  Called when an error occurs.
</ResponseField>

### Usage

```dart theme={null}
CrossmintEmailSignIn(
  auth: client.auth,
  onAuthenticated: () {
    print('Logged in!');
  },
)
```

***

## CrossmintGoogleSignInButton / CrossmintTwitterSignInButton

OAuth sign-in buttons.

### Props

<ResponseField name="auth" type="CrossmintAuthClient" required>
  The auth client instance.
</ResponseField>

<ResponseField name="onSuccess" type="VoidCallback">
  Called when OAuth authentication succeeds.
</ResponseField>

<ResponseField name="onError" type="void Function(Object)">
  Called when an error occurs.
</ResponseField>

<ResponseField name="enabled" type="bool">
  Whether the button is enabled. Defaults to `true`.
</ResponseField>

### Usage

```dart theme={null}
Column(
  children: [
    CrossmintGoogleSignInButton(auth: client.auth),
    const SizedBox(height: 12),
    CrossmintTwitterSignInButton(auth: client.auth),
  ],
)
```

***

## CrossmintExportPrivateKeyButton

Renders a button that allows the user to export their wallet's private key. Only works with email and phone signers. Will not render for passkey or external wallet signers.

### Props

<ResponseField name="wallet" type="CrossmintRuntimeWalletBase" required>
  The runtime wallet instance to export the private key from.
</ResponseField>

<ResponseField name="onExported" type="VoidCallback">
  Called when the private key has been exported successfully.
</ResponseField>

<ResponseField name="onError" type="void Function(Object)">
  Called when an error occurs during export.
</ResponseField>

<ResponseField name="childBuilder" type="CrossmintExportPrivateKeyButtonBuilder">
  Optional custom builder for the button appearance.
</ResponseField>

### Usage

```dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

CrossmintExportPrivateKeyButton(
  wallet: wallet,
  onExported: () => print('Key exported'),
)
```

> **Note:** Only works with email and phone signers. Will not render for passkey or external wallet signers.

***

## CrossmintEmbeddedCheckout

WebView-based checkout widget for handling payments (fiat and crypto).

### Props

<ResponseField name="apiKey" type="String" required>
  Your Crossmint client-side API key.
</ResponseField>

<ResponseField name="config" type="CrossmintCheckoutConfig" required>
  Checkout configuration (order, payment, appearance).
</ResponseField>

<ResponseField name="checkoutController" type="CrossmintCheckoutController">
  Optional reactive controller for checkout order state. When provided, order updates are pushed to the controller in addition to the `onOrderUpdated` callback.
</ResponseField>

<ResponseField name="payer" type="CrossmintCheckoutPayer">
  Optional crypto payer for signing transactions within checkout. Prefer `config.payment.crypto.payer` for the config-driven contract.
</ResponseField>

<ResponseField name="onOrderUpdated" type="void Function(Map<String, Object?>)">
  Callback fired when the order status changes.
</ResponseField>

<ResponseField name="onOrderCreationFailed" type="void Function(String)">
  Callback fired when order creation fails.
</ResponseField>

<ResponseField name="onDiagnostic" type="void Function(CrossmintCheckoutDiagnostic)">
  Callback for runtime diagnostics (blocked navigation, malformed messages, WebView errors).
</ResponseField>

### Usage

```dart theme={null}
final checkoutController = CrossmintCheckoutController();

CrossmintEmbeddedCheckout(
  apiKey: 'YOUR_CLIENT_API_KEY',
  config: CrossmintCheckoutConfig(
    order: CrossmintCheckoutNewOrder.typed(
      lineItems: [
        CrossmintCheckoutLineItem.collection(
          collectionLocator: 'crossmint:collection-id',
          callData: {'quantity': 1},
        ),
      ],
    ),
    payment: CrossmintCheckoutPayment(
      fiat: CrossmintCheckoutFiatPayment(enabled: true),
      crypto: CrossmintCheckoutCryptoPayment(enabled: false),
    ),
  ),
  checkoutController: checkoutController,
  onOrderUpdated: (order) => print('Order: ${order['status']}'),
  onOrderCreationFailed: (error) => print('Error: $error'),
)
```

***

## CrossmintNftCard / CrossmintNftCollectionView / CrossmintNftDetailView

Widgets for displaying NFT content. These are Flutter-only features not available in the React Native SDK.

### Usage

```dart theme={null}
// Single NFT card
CrossmintNftCard(
  nft: nftRecord,
  onTap: () => print('Tapped!'),
)

// Collection view
CrossmintNftCollectionView(
  nfts: nftList,
  onNftTap: (nft) => print('Tapped: ${nft.id}'),
)

// Detail view
CrossmintNftDetailView(
  nft: nftRecord,
)
```

***

## CrossmintPaymentMethodManagement

Widget for managing saved payment methods. This is a Flutter-only feature.

### Props

<ResponseField name="apiKey" type="String" required>
  Your Crossmint client-side API key.
</ResponseField>

<ResponseField name="jwt" type="String" required>
  The authenticated user's JWT token.
</ResponseField>

<ResponseField name="appearance" type="CrossmintCheckoutAppearance">
  Optional appearance configuration.
</ResponseField>

<ResponseField name="onPaymentMethodSelected" type="void Function(Map<String, Object?>)">
  Called when the user selects a payment method.
</ResponseField>

<ResponseField name="onAgenticEnrollmentCreated" type="void Function(Map<String, Object?>)">
  Called when an agentic enrollment is created.
</ResponseField>

### Usage

```dart theme={null}
CrossmintPaymentMethodManagement(
  apiKey: 'YOUR_CLIENT_API_KEY',
  jwt: session.jwt,
  onPaymentMethodSelected: (method) {
    print('Selected: $method');
  },
)
```