Join our community of builders on

Telegram!Telegram

Components

OpenZeppelin UIKit ships two categories of components: UI primitives from @openzeppelin/ui-components and renderer widgets from @openzeppelin/ui-renderer. This page catalogs both and shows how to use them.

UI Primitives

@openzeppelin/ui-components provides foundational React components built on Radix UI and shadcn/ui patterns. All components are styled with Tailwind CSS and support dark mode.

General Components

ComponentDescription
Button / LoadingButtonAction buttons with multiple variants (default, destructive, outline, secondary, ghost, link)
Input / TextareaText input primitives
LabelAccessible form labels
CardContainer with CardHeader, CardTitle, CardDescription, CardContent, CardFooter
DialogModal dialogs with DialogTrigger, DialogContent, DialogHeader, DialogFooter
AlertAlert messages with AlertTitle and AlertDescription
Checkbox / RadioGroupSelection inputs
SelectDropdown select with SelectTrigger, SelectContent, SelectItem
DropdownMenuContext menu with DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem
PopoverFloating content anchored to a trigger element
ProgressProgress bar indicator
TabsTab navigation with TabsList, TabsTrigger, TabsContent
TooltipHover tooltips
AccordionCollapsible content sections
BannerFull-width notification banners
Calendar / DateRangePickerDate selection and date-range picker components
EmptyStatePlaceholder UI for empty lists or initial states
ExternalLinkAnchor that opens in a new tab with appropriate rel attributes
FormForm wrapper integrating react-hook-form with accessible error messages
Header / FooterPage-level header and footer layout components
SonnerToast notification system (powered by sonner)
SidebarSidebar navigation layout
WizardMulti-step wizard flow

Blockchain-Specific Components

ComponentDescription
NetworkSelectorSearchable network dropdown with optional multi-select mode
NetworkIconNetwork-specific icon (renders the correct logo for a given network ID)
NetworkStatusBadgeColored badge showing network status (e.g. connected, syncing)
EcosystemDropdownEcosystem selection with chain icons
EcosystemIconChain-specific icons (Ethereum, Stellar, Polkadot, etc.)
AddressDisplayFormatted address with optional alias labels and edit controls
ViewContractStateButtonQuick-action button to open the contract state widget
OverflowMenuCompact "..." dropdown for secondary actions

Usage

import { Button, Card, CardContent, CardHeader, CardTitle } from '@openzeppelin/ui-components';

function ContractCard({ name, address }) {
  return (
    <Card>
      <CardHeader>
        <CardTitle>{name}</CardTitle>
      </CardHeader>
      <CardContent>
        <p className="text-sm text-muted-foreground">{address}</p>
        <Button variant="outline" className="mt-4">
          View Contract
        </Button>
      </CardContent>
    </Card>
  );
}

Form Fields

The field components are designed for use with react-hook-form. Each field handles its own validation, formatting, and blockchain-specific behavior.

FieldInput TypeUse Case
AddressFieldBlockchain addressContract addresses, recipient addresses; validates format per ecosystem
AmountFieldToken amountsToken transfers; handles decimals and BigInt formatting
BigIntFieldLarge integersRaw uint256 values, timestamps, token IDs
BytesFieldHex byte stringsCalldata, hashes, signatures
TextFieldFree-form textString parameters, names, URIs
UrlFieldURLEndpoint URLs, metadata URIs; validates URL format
PasswordFieldMasked textAPI keys, secrets; input is hidden by default
NumberFieldNumeric valuesCounts, percentages, indices
BooleanFieldTrue/falseFeature flags, approvals
EnumFieldEnum selectionContract enum parameters
SelectFieldDropdownPredefined option lists
SelectGroupedFieldGrouped dropdownCategorized options
RadioFieldRadio buttonsSmall option sets
TextAreaFieldMulti-line textABI input, JSON data
CodeEditorFieldCode / JSON editorContract source code, ABI JSON, configuration files
DateTimeFieldDate and timeTimestamps, scheduling, time-locked parameters
FileUploadFieldFile uploadImporting ABIs, uploading contract artifacts
ArrayFieldDynamic arraysArray parameters (e.g. address[], uint256[])
ArrayObjectFieldArray of structsRepeated struct entries (e.g. batch transfers, multi-recipient calls)
MapFieldKey-value pairsMapping-like structures
ObjectFieldNested objectsStruct/tuple parameters

Field Example

import { useForm } from 'react-hook-form';
import { AddressField, AmountField, Button } from '@openzeppelin/ui-components';

function TransferForm() {
  const { control, handleSubmit } = useForm({
    defaultValues: { to: '', amount: '' },
  });

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
      <AddressField
        name="to"
        label="Recipient"
        control={control}
        placeholder="0x..."
      />
      <AmountField
        name="amount"
        label="Amount"
        control={control}
        placeholder="0.0"
      />
      <Button type="submit">Transfer</Button>
    </form>
  );
}

Address Label & Suggestion Contexts

UIKit provides context-driven address resolution that works automatically with AddressField and AddressDisplay:

  • AddressLabelProvider: When mounted, all AddressDisplay instances in the subtree auto-resolve human-readable labels (e.g. "Treasury Multisig" instead of 0x1234...abcd).
  • AddressSuggestionProvider: When mounted, all AddressField instances show autocomplete suggestions as the user types.
  • useAddressLabel(address, networkId?): Hook to resolve a label from the nearest provider.

Renderer Widgets

@openzeppelin/ui-renderer provides high-level, ready-to-use widgets for common blockchain UI patterns. These compose the lower-level components with adapter capabilities.

TransactionForm and dynamic fields in the example app

TransactionForm

The primary widget for rendering blockchain transaction forms. Accepts a declarative schema and an adapter capabilities bundle:

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

const schema: RenderFormSchema = {
  id: 'approve-form',
  title: 'Approve Spending',
  fields: [
    { id: 'spender', name: 'spender', type: 'address', label: 'Spender' },
    { id: 'amount', name: 'amount', type: 'amount', label: 'Amount' },
  ],
  layout: { columns: 1, spacing: 'normal', labelPosition: 'top' },
  submitButton: { text: 'Approve', loadingText: 'Approving...' },
};

function ApprovePage({ adapter }: { adapter: TransactionFormCapabilities }) {
  return (
    <TransactionForm
      schema={schema}
      adapter={adapter}
      onTransactionSuccess={(result) => console.log('Approved:', result)}
    />
  );
}

Key props:

PropTypeDescription
schemaRenderFormSchemaForm layout, fields, and submit button config
contractSchemaContractSchemaABI / function metadata for the target contract
adapterTransactionFormCapabilitiesCapability bundle from the active runtime
executionConfigExecutionConfigEOA vs. relayer configuration
onTransactionSuccesscallbackFires after successful transaction
isWalletConnectedbooleanWhether a wallet session is active

DynamicFormField

Renders individual form fields dynamically based on type configuration. Used internally by TransactionForm but available for custom form layouts:

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

<DynamicFormField
  field={{ id: 'amount', name: 'amount', type: 'amount', label: 'Amount' }}
  control={control}
/>

ContractStateWidget

ContractStateWidget

Displays read-only contract state by querying view functions. The widget automatically discovers all view functions from the contract schema and renders their return types. Supports auto-refresh to keep values current.

Each row shows the function name, return type, and live result. No wallet connection is required. Pass query and schema capabilities from the active runtime:

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

<ContractStateWidget
  contractSchema={contractSchema}
  contractAddress="0x..."
  query={runtime.query}
  schema={runtime.schema}
  isVisible={true}
/>

AddressBookWidget

A full-featured address book UI for managing saved addresses and their human-readable aliases. Supports CRUD operations, search, and import/export.

AddressBookWidget

AddressBookWidget works with the @openzeppelin/ui-storage package, specifically the account alias plugin which persists address-to-name mappings in IndexedDB via Dexie.js. When mounted alongside AddressLabelProvider and AddressSuggestionProvider, saved aliases automatically appear in all AddressDisplay and AddressField components throughout the app.

import { AddressBookWidget } from '@openzeppelin/ui-renderer';
import { createDexieDatabase, ALIAS_SCHEMA, useAddressBookWidgetProps } from '@openzeppelin/ui-storage';
import Dexie from 'dexie';

const db = createDexieDatabase(new Dexie('my-app'), ALIAS_SCHEMA);

function AddressBook({ addressing }) {
  const widgetProps = useAddressBookWidgetProps(db, { networkId: 'ethereum-mainnet' });
  return <AddressBookWidget {...widgetProps} addressing={addressing} />;
}

See the Storage page for setup and plugin configuration.

Other Renderer Components

ComponentDescription
ContractActionBarNetwork status display with contract state toggle
ExecutionConfigDisplayConfigure execution method (EOA / Relayer)
NetworkSettingsDialogConfigure RPC endpoints and indexer URLs
WalletConnectionWithSettingsWallet connection UI with integrated settings
AliasEditPopoverInline popover for editing address aliases

Next Steps