Finality UX Kit — Free Sampler

One React/Tailwind card and eight editable wallet and transaction copy examples. Use it to prototype connection, network, signature, approval, pending, finalized, and reverted states with explicit recovery instructions.

The package renders the state you supply. It does not connect a wallet, send transactions, verify payments, or advance a flow automatically. These are independent state examples, not a complete payment flow. Base, amounts and transaction details are illustrative: replace them with data verified by your application. Transition entries describe examples; external: targets require your application's logic. A signed message alone does not prove submission, and a token approval is not a completed transfer.

Show the finalized example only after verifying the intended transfer and the network's finalized block. An application's confirmation threshold does not establish network finality. The approval example uses an ERC-20 allowance: a partial spend can leave an allowance, and ordinary approve has no expiry. See Base transaction finality and the ERC-20 approval specification.

For the free SVG import board, copy CSV and JSON, download the full free sampler. The separate Finality Core Kit adds an eleven-state transfer flow, native Figma components and a typed React controller.

Install

npm install finality-ux-sampler react

React 18.2 or 19 and Tailwind CSS 3.4 or 4 are supported. Runtime exports are compiled ESM; your application does not need to transpile JSX inside this package. CommonJS require() is not the supported interface. TypeScript declarations cover the root and finality-ux-sampler/states exports.

Include Tailwind styles

The package ships utility classes, not a stylesheet. Tailwind normally excludes node_modules, so add the package explicitly to your existing Tailwind setup.

For Tailwind 4, in src/app.css:

@import "tailwindcss";
@source "../node_modules/finality-ux-sampler/src";

The @source path is relative to that CSS file. Adjust it if your stylesheet lives elsewhere.

For Tailwind 3.4, add this entry to tailwind.config.js in your project root:

export default {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/finality-ux-sampler/src/**/*.jsx",
  ],
  theme: { extend: {} },
  plugins: [],
};

Keep your app's existing content paths, theme and plugins when merging this example. The card uses fixed utility names, so all five tones can be detected.

Render a state

import { FinalityStateCard, finalityStates } from "finality-ux-sampler";

export function PendingCard({ transaction, onViewActivity, onCopyId }) {
  const example = finalityStates.find(s => s.id === "transaction.pending");
  const state = {
    ...example,
    title: "Your transfer is processing",
    status: "Submitted",
    body: `Transfer ${transaction.id} was submitted. Check its existing result.`,
  };

  return (
    <FinalityStateCard
      state={state}
      onPrimaryAction={onViewActivity}
      onSecondaryAction={() => onCopyId(transaction.id)}
    />
  );
}

Pass callbacks for the actions your app supports. A missing callback disables its button. disabled={true} disables both actions while your own operation is pending. Callbacks receive the displayed state; the host owns network requests, timeouts, duplicate-submission prevention, error handling and focus after a wallet dialog. In a Next.js App Router app, render the interactive card from a client component with "use client".

Catalog and types

import { finalityCatalog, finalityStates } from "finality-ux-sampler/states";
import type { FinalityState, FinalityStateId } from "finality-ux-sampler/states";

The plain JSON export is finality-ux-sampler/states.json; import it using the JSON-module syntax supported by your runtime or bundler.

| State ID | Example | | --- | --- | | wallet.disconnected | Choose a wallet | | network.unsupported | Review the expected network | | signature.requested | Review a signature | | signature.rejected | Recover from rejection | | approval.requested | Review a spending cap | | transaction.pending | Check an existing transaction | | transaction.finalized | Review a verified receipt | | transaction.reverted | Review a revert before retrying |

The sampler does not include an unknown-result card. Treat a timeout as an unknown outcome in your host flow, preserve the original request, and check it before allowing a retry that could send money again.

License and support

Code is MIT; design and interface copy are CC BY 4.0. See LICENSE and ATTRIBUTION.md for the file boundaries and a ready-to-use credit. The separate paid Core Kit has its own license. No analytics or tracking is included here.

Support.