Widgets

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

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

Introduction

Quickstarts ⚡️

Concepts

Guides

API Reference

CrossmintWalletStatusBuilder

Props

Usage

CrossmintWalletConsumer

Usage

CrossmintWalletUiState (`data.state`)

CrossmintOtpSignerListener

Props

Usage

CrossmintAuthForm

Props

Usage

CrossmintEmailSignIn

Props

Usage

CrossmintGoogleSignInButton / CrossmintTwitterSignInButton

Props

Usage

CrossmintExportPrivateKeyButton

Props

Usage

CrossmintEmbeddedCheckout

Props

Usage

CrossmintNftCard / CrossmintNftCollectionView / CrossmintNftDetailView

Usage

CrossmintPaymentMethodManagement

Props

Usage

Introduction

Quickstarts ⚡️

Concepts

Guides

API Reference

​CrossmintWalletStatusBuilder

​Props

​Usage

​CrossmintWalletConsumer

​Usage

​CrossmintWalletUiState (data.state)

​CrossmintOtpSignerListener

​Props

​Usage

​CrossmintAuthForm

​Props

​Usage

​CrossmintEmailSignIn

​Props

​Usage

​CrossmintGoogleSignInButton / CrossmintTwitterSignInButton

​Props

​Usage

​CrossmintExportPrivateKeyButton

​Props

​Usage

​CrossmintEmbeddedCheckout

​Props

​Usage

​CrossmintNftCard / CrossmintNftCollectionView / CrossmintNftDetailView

​Usage

​CrossmintPaymentMethodManagement

​Props

​Usage

CrossmintWalletStatusBuilder

Props

Usage

CrossmintWalletConsumer

Usage

CrossmintWalletUiState (`data.state`)

CrossmintOtpSignerListener

Props

Usage

CrossmintAuthForm

Props

Usage

CrossmintEmailSignIn

Props

Usage

CrossmintGoogleSignInButton / CrossmintTwitterSignInButton

Props

Usage

CrossmintExportPrivateKeyButton

Props

Usage

CrossmintEmbeddedCheckout

Props

Usage

CrossmintNftCard / CrossmintNftCollectionView / CrossmintNftDetailView

Usage

CrossmintPaymentMethodManagement

Props

Usage