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 · CrossmintWalletStatusWidgetBuilder · required

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'),
    );
  },
)

---

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

child · Widget · required

enabled · bool

barrierDismissible · bool

Usage

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

---

CrossmintAuthForm

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

Props

auth · CrossmintAuthClient · required

providers · List<CrossmintOAuthProvider>

showEmailSignIn · bool

authModalTitle · String?

Custom title shown on the OTP verification step (e.g. “Sign in to Acme”).

onAuthenticated · VoidCallback?

onError · void Function(Object error)?

Usage

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

---

CrossmintEmailSignIn

Email OTP sign-in form widget.

Props

auth · CrossmintAuthClient · required

viewModel · CrossmintEmailSignInViewModel?

Optional view model override. When null, the widget constructs a fresh [CrossmintEmailSignInViewModel] bound to [auth] and disposes it with the widget. When provided, the widget observes the view model but does not dispose it — the caller owns the lifecycle.

Show properties

auth · CrossmintAuthClient · required

cooldownDuration · Duration

Duration of the resend cooldown. Defaults to 60 seconds to match the React Native Crossmint SDK. Lowered in tests to keep them fast.

otpTitle · String?

Custom title for the OTP verification step. Defaults to 'Check your email'.

onAuthenticated · VoidCallback?

onError · void Function(Object error)?

Usage

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

---

CrossmintGoogleSignInButton / CrossmintTwitterSignInButton

OAuth sign-in buttons.

Props

auth · CrossmintAuthClient · required

Auth client used to start the OAuth flow.

onSuccess · VoidCallback?

Called after the OAuth flow completes successfully. Use this to navigate away or refresh dependent state.

onError · void Function(Object error)?

Called when the OAuth flow throws. Receives the underlying exception so consumers can surface a localized error message.

enabled · bool

When false, the button is rendered in a disabled visual state and taps do not start the OAuth flow. 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

Wallet whose private key will be exported. The button only renders when [CrossmintRuntimeWalletBase.canExportPrivateKey] is true (email/phone signer wallets).

Show properties

client · CrossmintClient · required

Top-level Crossmint client shared by all wallet operations.

Show properties

config · CrossmintClientConfig · required

auth · CrossmintAuthClient?

wallets · CrossmintWalletsClient?

credentials · CrossmintCredentialsClient?

orders · CrossmintOrdersClient?

tokens · CrossmintTokensClient?

users · CrossmintUsersClient?

transport · CrossmintTransport?

authLauncher · CrossmintAuthLauncher?

runtimeOverrides · CrossmintClientRuntimeOverrides?

wallet · CrossmintWallet · required

Server-issued wallet snapshot backing this runtime instance.

Show properties

id · String · required

chain · String?

address · String?

owner · String?

raw · CrossmintJsonMap

recoverySigner · CrossmintSignerConfig?

signer · CrossmintWalletApprovalSigner?

additionalSigners · List<CrossmintWalletApprovalSigner>

deviceSignerKeyStorage · DeviceSignerKeyStorage?

Storage backend for hardware-backed device signer keys.

onAuthRequired · CrossmintSignerAuthRequiredCallback?

Callback invoked when a signer operation requires user authentication.

onExported · VoidCallback?

Called after the export flow completes successfully.

onError · void Function(Object error)?

Called when the export flow throws. Receives the underlying exception so consumers can surface a localized error message.

childBuilder · CrossmintExportPrivateKeyButtonBuilder?

Optional builder for the button visual. When null, falls back to the React Native parity Material OutlinedButton with a themed CircularProgressIndicator while the export is in flight. When non-null, the builder is invoked whenever the wallet is eligible to export and receives the current isLoading flag plus an onExport callback that the consumer wires to their own tap target. The onExport callback is null while loading so consumers can disable their button directly without a separate mounted check.

Usage

import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

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

---

CrossmintEmbeddedCheckout

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

Props

apiKey · String · required

Crossmint API key.

config · CrossmintCheckoutConfig · required

Checkout configuration (order, payment, appearance).

Show properties

order · CrossmintCheckoutOrder · required

Order to check out — either a [CrossmintCheckoutNewOrder] built from line items, or a [CrossmintCheckoutExistingOrder] referencing an already-created order by id.

payment · CrossmintCheckoutPayment · required

Payment method configuration — fiat, crypto, and default method.

Show properties

fiat · CrossmintCheckoutFiatPayment?

Fiat (card, Apple Pay, Google Pay) configuration — null disables the fiat tab entirely.

crypto · CrossmintCheckoutCryptoPayment?

Crypto payment configuration — null disables the crypto tab.

defaultMethod · String?

Raw default payment method string. Prefer [defaultMethodType] for compile-time safety. When both are set, [defaultMethodType] wins.

defaultMethodType · CrossmintCheckoutDefaultMethod?

Typed default payment method — one of [CrossmintCheckoutDefaultMethod]: fiat (open on credit card / Apple Pay / Google Pay) or crypto (open on on-chain payment). Takes precedence over [defaultMethod].

receiptEmail · String?

Email to receive the order receipt. Leave null to use the recipient email (for [CrossmintCheckoutEmailRecipient]) or rely on the user entering an email inside the hosted page.

appearance · CrossmintCheckoutAppearance?

Optional appearance customization — CSS variables, rules, fonts.

Show properties

variables · Map<String, Object?>?

CSS custom properties for theming (e.g. {'colorPrimary': '#0F172A'}).

rules · Map<String, Object?>?

CSS rules for specific checkout elements (e.g. {'.Input': {'borderColor': '#CBD5E1'}}).

fonts · List<Map<String, String>>?

Custom font definitions (e.g. [{'cssSrc': 'https://fonts.googleapis.com/...'}]).

jwt · String?

Optional JWT for authenticated checkouts — attaches the user’s Crossmint session to the hosted page so the experience is signed-in when the user lands. Pass client.auth.state.session?.jwt when you want the checkout to inherit the current app session.

payer · CrossmintCheckoutPayer?

Optional crypto payer override for signing transactions within checkout.

checkoutController · CrossmintCheckoutController?

Optional reactive controller for checkout order state.

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

Called when the order state changes.

onOrderCreationFailed · void Function(String errorMessage)?

Called when order creation fails.

onDiagnostic · void Function(CrossmintCheckoutDiagnostic diagnostic)?

Called when the hosted checkout emits a runtime diagnostic.

loadingBuilder · CrossmintCheckoutLoadingBuilder?

Optional builder for the loading overlay rendered on top of the hosted checkout WebView while the page is loading. When null, the widget falls back to a Material CircularProgressIndicator inside a themed background container (the React Native Crossmint SDK parity default).

defaultHeight · double

Initial height before the hosted page reports its actual height.

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

Crossmint API key.

jwt · String · required

JWT token for authenticated access (required by the hosted page).

appearance · CrossmintCheckoutAppearance?

Optional appearance overrides (reuses the checkout appearance config).

Show properties

variables · Map<String, Object?>?

CSS custom properties for theming (e.g. {'colorPrimary': '#0F172A'}).

rules · Map<String, Object?>?

CSS rules for specific checkout elements (e.g. {'.Input': {'borderColor': '#CBD5E1'}}).

fonts · List<Map<String, String>>?

Custom font definitions (e.g. [{'cssSrc': 'https://fonts.googleapis.com/...'}]).

onPaymentMethodSelected · dynamic

onAgenticEnrollmentCreated · dynamic

loadingBuilder · CrossmintPaymentMethodManagementLoadingBuilder?

Optional builder for the loading overlay rendered on top of the hosted payment-method-management WebView while the page is loading. When null, the widget falls back to a Material CircularProgressIndicator inside a themed background container (the React Native Crossmint SDK parity default).

defaultHeight · double

Initial height before the hosted page reports its actual height.

Usage

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

---

CrossmintWalletUiState (data.state)

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

Field / getter	Type	Description
isInitializing	bool
isLoadingWallet	bool
authState	CrossmintAuthState
walletStatus	CrossmintWalletStatus
currentWallet	CrossmintWallet?
pendingOtpChallenge	CrossmintOtpChallenge?
initializationError	Object?
walletError	Object?
isAuthenticated	bool
isLoggedOut	bool
user	CrossmintAuthenticatedUser?
authErrorMessage	String?
error	Object?
errorMessage	String?
hasWallet	bool
needsOtp	bool