renderer

@openzeppelin/ui-renderer

React components for rendering blockchain transaction forms, contract state displays, and wallet interactions.

Installation

# Using npm
npm install @openzeppelin/ui-renderer @openzeppelin/ui-types

# Using yarn
yarn add @openzeppelin/ui-renderer @openzeppelin/ui-types

# Using pnpm
pnpm add @openzeppelin/ui-renderer @openzeppelin/ui-types

Peer Dependencies

pnpm add react react-dom react-hook-form

Features

• Transaction form rendering with dynamic field generation
• Contract state querying and display (view functions)
• Transaction status tracking with explorer links
• Execution method configuration (EOA/Relayer)
• Network settings and wallet connection components
• TypeScript support with full type definitions
• Support for both ESM and CommonJS environments

Components

TransactionForm

Main component for rendering blockchain transaction forms with dynamic field generation.

ContractStateWidget

Widget for querying and displaying contract state through view functions. Supports parameter-less view functions with auto-refresh capabilities.

ContractActionBar

Action bar component displaying network status and contract state toggle controls.

ExecutionConfigDisplay

Displays and configures transaction execution methods (EOA direct signing or Relayer-based).

TransactionStatusDisplay

Shows transaction progress, hash display with explorer links, and execution results.

NetworkSettingsDialog

Dialog for configuring network-specific settings like RPC endpoints and indexer URLs.

WalletConnectionWithSettings

Composed wallet connection component with integrated settings controls.

AddressBookWidget

Full-featured widget for managing a personal address book with aliases, search, network filtering, import/export, and CRUD operations. Designed to receive all data and mutations via props (dependency injection) from useAddressBookWidgetProps in @openzeppelin/ui-storage.

AliasEditPopover

Floating popover for inline alias editing. Positioned near the edit trigger via an anchor rect. Includes address lookup and save/create functionality.

useAliasEditState

Pure UI state hook for managing the inline alias edit popover. Returns editing, onEditLabel, handleClose, and lastClickRef for coordinating popover display with AddressLabelProvider.

DynamicFormField

Renders form fields dynamically based on field type configuration.

Type System

This package uses type definitions from @openzeppelin/ui-types. Form and state widgets take capability intersections (for example TransactionFormCapabilities, QueryCapability + SchemaCapability) rather than a single monolithic adapter type:

import { TransactionForm } from '@openzeppelin/ui-renderer';
import type { FormValues, RenderFormSchema, TransactionFormCapabilities } from '@openzeppelin/ui-types';

Component Styling

This package renders forms using UI components from @openzeppelin/ui-components. This package does not ship pre-compiled CSS.

Styling relies on the consuming application to:

1. Include Tailwind CSS in its build process.
2. Configure Tailwind to scan the OpenZeppelin UI and adapter packages that provide class names.
3. Import the shared theme from @openzeppelin/ui-styles.

For consumer apps that use @openzeppelin/ui-dev-cli, the recommended workflow is:

pnpm exec oz-ui-dev tailwind doctor --project "$PWD"
pnpm exec oz-ui-dev tailwind fix --project "$PWD"

That generates a managed oz-tailwind.generated.css file so Tailwind v4 always sees the required @source entries.

If you need to wire Tailwind manually, use explicit @source directives instead of a bare import:

@layer base, components, utilities;

@import 'tailwindcss' source(none);
@source "../node_modules/@openzeppelin/ui-components";
@source "../node_modules/@openzeppelin/ui-react";
@source "../node_modules/@openzeppelin/ui-renderer";
@source "../node_modules/@openzeppelin/ui-styles";
@source "../node_modules/@openzeppelin/ui-utils";
@import '@openzeppelin/ui-styles/global.css';

Usage

Transaction Form

TransactionForm expects an adapter prop typed as TransactionFormCapabilities (execution, schema, type mapping, wallet-related pieces, etc., depending on profile). Derive it from your active EcosystemRuntime (for example by intersecting the capabilities your app uses) or pass the object your ecosystem exposes for transaction authoring.

import { TransactionForm } from '@openzeppelin/ui-renderer';
import type { RenderFormSchema, TransactionFormCapabilities } from '@openzeppelin/ui-types';

const schema: RenderFormSchema = {
  id: 'transfer-form',
  title: 'Transfer Tokens',
  fields: [
    { id: 'to', name: 'to', type: 'address', label: 'Recipient' },
    { id: 'amount', name: 'amount', type: 'amount', label: 'Amount' },
  ],
  layout: { columns: 1, spacing: 'normal', labelPosition: 'top' },
  submitButton: { text: 'Transfer', loadingText: 'Transferring...' },
};

function App({
  adapter,
  contractSchema,
}: {
  adapter: TransactionFormCapabilities;
  contractSchema: import('@openzeppelin/ui-types').ContractSchema;
}) {
  return (
    <TransactionForm
      schema={schema}
      contractSchema={contractSchema}
      adapter={adapter}
      onTransactionSuccess={handleTransactionSuccess}
    />
  );
}

Contract State Widget

ContractStateWidget extends ContractStateCapabilityProps: pass query and schema capabilities (from the active runtime) so view calls use the same network and schema pipeline as the rest of the app.

import { ContractStateWidget } from '@openzeppelin/ui-renderer';

function ContractView({
  query,
  schema,
}: {
  query: import('@openzeppelin/ui-types').QueryCapability;
  schema: import('@openzeppelin/ui-types').SchemaCapability;
}) {
  return (
    <ContractStateWidget
      contractSchema={contractSchema}
      contractAddress="0x..."
      query={query}
      schema={schema}
      isVisible={true}
    />
  );
}

Contract Action Bar

import { ContractActionBar } from '@openzeppelin/ui-renderer';

function FormHeader() {
  return (
    <ContractActionBar
      networkConfig={networkConfig}
      contractAddress={contractAddress}
      onToggleContractState={handleToggle}
    />
  );
}

API Reference

<TransactionForm>

See TransactionFormProps in @openzeppelin/ui-types for the full contract. Important props:

Prop	Type	Description
schema	RenderFormSchema	Form layout and fields
contractSchema	ContractSchema (optional)	ABI / function metadata for the target call
adapter	TransactionFormCapabilities	Capability bundle for signing, mapping, execution
executionConfig	ExecutionConfig (optional)	EOA vs relayer and related options
onTransactionSuccess	callback (optional)	Fires after a successful transaction lifecycle
isWalletConnected	boolean (optional)	Whether a wallet session is present

Network configuration is taken from adapter.networkConfig (see RuntimeCapability).

<ContractStateWidget>

Implements ContractStateCapabilityProps plus display props:

Prop	Type	Description
contractSchema	ContractSchema | null	Contract schema with view functions
contractAddress	string | null	Deployed contract address
query	QueryCapability	View/query capability (includes networkConfig)
schema	SchemaCapability	Schema capability for the active network
isVisible	boolean	(Optional) Controls widget visibility
onToggle	() => void	(Optional) Toggle callback
error	Error | null	(Optional) External error to surface

<ContractActionBar>

Prop	Type	Description
networkConfig	NetworkConfig	Network configuration to display
contractAddress	string	(Optional) Contract address
onToggleContractState	() => void	(Optional) Toggle contract state widget
isWidgetExpanded	boolean	(Optional) Current widget expanded state

Address Book Usage

import { AddressBookWidget, AliasEditPopover, useAliasEditState } from '@openzeppelin/ui-renderer';
import { useAddressBookWidgetProps, useAliasEditCallbacks } from '@openzeppelin/ui-storage';

function Settings() {
  const widgetProps = useAddressBookWidgetProps(db, { networkId: selectedNetwork?.id });
  const editCallbacks = useAliasEditCallbacks(db);
  const { editing, onEditLabel, handleClose, lastClickRef } = useAliasEditState(
    selectedNetwork?.id
  );

  return (
    <div
      onPointerDown={(e) => {
        lastClickRef.current = { x: e.clientX, y: e.clientY };
      }}
    >
      <AddressBookWidget {...widgetProps} />
      {editing && <AliasEditPopover {...editing} onClose={handleClose} {...editCallbacks} />}
    </div>
  );
}

Package Structure

renderer/
├── src/
│   ├── components/
│   │   ├── AddressBookWidget/       # Address book management widget
│   │   ├── ContractActionBar/       # Network status and actions
│   │   ├── ContractStateWidget/     # View function queries
│   │   ├── ExecutionConfigDisplay/  # EOA/Relayer configuration
│   │   ├── network/                 # Network settings components
│   │   ├── transaction/             # Transaction status components
│   │   ├── TransactionForm.tsx      # Main form component
│   │   └── DynamicFormField.tsx     # Dynamic field rendering
│   ├── types/
│   ├── utils/
│   └── index.ts
├── package.json
├── tsconfig.json
└── tsdown.config.ts

Development

pnpm install
pnpm build
pnpm test
pnpm lint

License

AGPL-3.0