OpenZeppelin UI

A modular React component library for building blockchain transaction interfaces.

Packages

This monorepo contains the following packages:

Package	Description	npm
@openzeppelin/ui-types	Shared TypeScript type definitions
@openzeppelin/ui-utils	Framework-agnostic utility functions
@openzeppelin/ui-styles	Centralized styling system (Tailwind CSS 4)
@openzeppelin/ui-components	React UI components (shadcn/ui based)
@openzeppelin/ui-renderer	Transaction form rendering engine
@openzeppelin/ui-react	React context providers and hooks
@openzeppelin/ui-storage	IndexedDB storage abstraction (Dexie.js)

Installation

Install the packages you need:

# Core types and utilities
pnpm add @openzeppelin/ui-types @openzeppelin/ui-utils

# UI components
pnpm add @openzeppelin/ui-components @openzeppelin/ui-styles

# Form rendering
pnpm add @openzeppelin/ui-renderer

# React integration
pnpm add @openzeppelin/ui-react

# Storage (optional)
pnpm add @openzeppelin/ui-storage

Quick Start

1. Setup Styles

Import the global styles and Tailwind CSS in your app's entry CSS:

@import '@openzeppelin/ui-styles/global.css';
@import 'tailwindcss';

2. Use Components

import { useForm } from 'react-hook-form';

import { Button, TextField } from '@openzeppelin/ui-components';

function MyForm() {
  const { control, handleSubmit } = useForm();

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <TextField name="recipient" label="Recipient Address" control={control} placeholder="0x..." />
      <Button type="submit">Send Transaction</Button>
    </form>
  );
}

3. Render Transaction Forms

import { TransactionForm } from '@openzeppelin/ui-renderer';
import type { RenderFormSchema } 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 TransferPage() {
  return (
    <TransactionForm
      schema={schema}
      adapter={myAdapter}
      networkConfig={networkConfig}
      onSubmit={handleSubmit}
    />
  );
}

Architecture

Layer	Package	Purpose
App	Your Application	Consumer application
6	@openzeppelin/ui-react	Context providers & hooks
5	@openzeppelin/ui-renderer	Form & contract UI rendering
4	@openzeppelin/ui-components	UI primitives & form fields
3	@openzeppelin/ui-styles	Tailwind theme & variables
2	@openzeppelin/ui-utils	Shared utilities
1	@openzeppelin/ui-types	Type definitions

Requirements

• Node.js >= 20.19.0
• React 19
• Tailwind CSS 4

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Lint
pnpm lint

# Type check
pnpm typecheck

Local Development (Consuming Projects)

If you're developing a project that uses @openzeppelin/ui-* packages and want to test changes against a local checkout of this repo, run the setup script:

# From your project directory (with openzeppelin-ui as a sibling):
node ../openzeppelin-ui/scripts/setup-local-dev.mjs

# Or with a custom path:
node /path/to/openzeppelin-ui/scripts/setup-local-dev.mjs --ui-path ../my-ui-fork

This creates a .pnpmfile.cjs hook and adds convenience scripts to your package.json:

pnpm dev:local   # Use local UI Kit packages
pnpm dev:npm     # Switch back to npm packages

Contributing

See CONTRIBUTING.md for development guidelines.

Documentation

• Migration Guide - Migrate from @openzeppelin/ui-builder-* packages
• DevOps Setup Guide - CI/CD secrets and GitHub App configuration
• Operations Runbook - Release management and incident procedures

License

AGPL-3.0