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 directly.

---

CrossmintWalletStatusBuilder

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

Props

builder · 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.

Usage

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

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

otpController · CrossmintWalletOtpController · required

The OTP controller from the wallet controller (e.g. walletController.otp).

child · Widget · required

The widget subtree.

enabled · bool

Whether the listener is active. Defaults to true.

barrierDismissible · bool

Whether the OTP dialog can be dismissed by tapping outside. Defaults to false.

Usage

CrossmintOtpSignerListener(
  otpController: walletController.otp,
  child: const WalletScreen(),
)

---

CrossmintAuthForm

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

Props

auth · CrossmintAuthClient · required

The auth client instance (e.g. client.auth or data.requireAuth).

providers · List<CrossmintOAuthProvider>

OAuth providers to display. Defaults to [google, twitter].

showEmailSignIn · bool

Whether to show the email OTP form. Defaults to true.

onAuthenticated · VoidCallback

Called when authentication succeeds.

onError · void Function(Object)

Called when an error occurs during authentication.

Usage

CrossmintAuthForm(
  auth: client.auth,
  onAuthenticated: () {
    print('Logged in!');
  },
)

---

CrossmintEmailSignIn

Email OTP sign-in form widget.

Props

auth · CrossmintAuthClient · required

The auth client instance.

onAuthenticated · VoidCallback

Called when email OTP authentication succeeds.

onError · void Function(Object)

Called when an error occurs.

Usage

CrossmintEmailSignIn(
  auth: client.auth,
  onAuthenticated: () {
    print('Logged in!');
  },
)

---

CrossmintGoogleSignInButton / CrossmintTwitterSignInButton

OAuth sign-in buttons.

Props

auth · CrossmintAuthClient · required

The auth client instance.

onSuccess · VoidCallback

Called when OAuth authentication succeeds.

onError · void Function(Object)

Called when an error occurs.

enabled · bool

Whether the button is enabled. Defaults to true.

Usage

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

wallet · CrossmintRuntimeWalletBase · required

The runtime wallet instance to export the private key from.

onExported · VoidCallback

Called when the private key has been exported successfully.

onError · void Function(Object)

Called when an error occurs during export.

childBuilder · CrossmintExportPrivateKeyButtonBuilder

Optional custom builder for the button appearance.

Usage

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

apiKey · String · required

Your Crossmint client-side API key.

config · CrossmintCheckoutConfig · required

Checkout configuration (order, payment, appearance).

checkoutController · CrossmintCheckoutController

Optional reactive controller for checkout order state. When provided, order updates are pushed to the controller in addition to the onOrderUpdated callback.

payer · CrossmintCheckoutPayer

Optional crypto payer for signing transactions within checkout. Prefer config.payment.crypto.payer for the config-driven contract.

onOrderUpdated · void Function(Map<String, Object?>)

Callback fired when the order status changes.

onOrderCreationFailed · void Function(String)

Callback fired when order creation fails.

onDiagnostic · void Function(CrossmintCheckoutDiagnostic)

Callback for runtime diagnostics (blocked navigation, malformed messages, WebView errors).

Usage

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

// 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

apiKey · String · required

Your Crossmint client-side API key.

jwt · String · required

The authenticated user’s JWT token.

appearance · CrossmintCheckoutAppearance

Optional appearance configuration.

onPaymentMethodSelected · void Function(Map<String, Object?>)

Called when the user selects a payment method.

onAgenticEnrollmentCreated · void Function(Map<String, Object?>)

Called when an agentic enrollment is created.

Usage

CrossmintPaymentMethodManagement(
  apiKey: 'YOUR_CLIENT_API_KEY',
  jwt: session.jwt,
  onPaymentMethodSelected: (method) {
    print('Selected: $method');
  },
)