@openzeppelin/ui-react

Core React context providers and hooks for the OpenZeppelin UI ecosystem.


Installation

``bash


Using npm

`bash
pnpm add react react-dom @tanstack/react-query
`

Overview

This package provides core React context providers and hooks that centralize the management of global wallet state, active network selection, active adapter instances, and the consumption of adapter-specific UI capabilities.

It is a foundational package that can be used to ensure consistent wallet and adapter integration patterns across applications.

Core Responsibilities

- Adapter Instance Management: Provides AdapterProvider which maintains a registry of ContractAdapter instances, ensuring only one instance exists per network configuration (singleton pattern).
- Global Wallet/Network State Management: Provides WalletStateProvider which manages:
- The globally selected active network ID and its corresponding NetworkConfig.
- The active ContractAdapter instance for this global network and its loading state.
- The EcosystemSpecificReactHooks (facade hooks) provided by the active adapter.
- Orchestration of rendering the active adapter's UI context provider.
- Consistent State Access: Exports consumer hooks for components to access this managed state and functionality.

Key Exports

$3

- AdapterProvider: Manages adapter instances. Requires a resolveAdapter prop to fetch/create adapters.
- WalletStateProvider: Manages global active network/adapter/wallet state.

$3

- useAdapterContext(): Access AdapterProvider's getAdapterForNetwork function.
- useWalletState(): Access global state like activeNetworkId, activeAdapter, walletFacadeHooks, and setActiveNetworkId.

$3

These hooks abstract wallet interactions and work with any adapter implementing the facade pattern:

- useDerivedAccountStatus(): Returns connection status, address, and current chain ID.
- useDerivedSwitchChainStatus(): Returns the switchChain function and switching state.
- useDerivedChainInfo(): Returns current chain information.
- useDerivedConnectStatus(): Returns wallet connection functions and state.
- useDerivedDisconnect(): Returns the disconnect function.
- useWalletReconnectionHandler(): Detects wallet reconnection and triggers network switch re-queue.

$3

- WalletConnectionHeader: Compact wallet connection status display.
- WalletConnectionUI: Full wallet connection interface.
- WalletConnectionWithSettings: Wallet connection UI with settings controls.
- NetworkSwitchManager: Handles automatic wallet network switching for EVM chains.

Usage

$3

`tsx
import { AdapterProvider, WalletStateProvider } from '@openzeppelin/ui-react';

import { getAdapter, getNetworkById } from './core/ecosystemManager';

function AppRoot() {
return (

initialNetworkId="ethereum-mainnet"
getNetworkConfigById={getNetworkById}
>
{/ Your application components /}


);
}
`

$3

`tsx
import { useWalletState } from '@openzeppelin/ui-react';

function MyWalletComponent() {
const {
activeNetworkId,
activeNetworkConfig,
activeAdapter,
isAdapterLoading,
walletFacadeHooks,
setActiveNetworkId,
} = useWalletState();

if (isAdapterLoading || !activeAdapter) {
return

Loading wallet information...

`tsx
import { useState } from 'react';

import { NetworkSwitchManager } from '@openzeppelin/ui-react';

function MyApp() {
const [networkToSwitchTo, setNetworkToSwitchTo] = useState(null);
const adapter = useMyAdapter();

const handleNetworkSwitchComplete = () => {
setNetworkToSwitchTo(null);
};

return (
<>
{adapter && networkToSwitchTo && (
adapter={adapter}
targetNetworkId={networkToSwitchTo}
onNetworkSwitchComplete={handleNetworkSwitchComplete}
/>
)}

);
}
`

Package Structure

`text
react/
├── src/
│ ├── components/ # UI components (WalletConnection*, NetworkSwitchManager)
│ ├── hooks/ # Context providers and consumer hooks
│ └── index.ts # Main package exports
├── package.json
├── tsconfig.json
├── tsdown.config.ts
└── README.md
`

Dependencies

This package has minimal dependencies to maintain a lightweight footprint:

- @openzeppelin/ui-types: Shared type definitions
- @openzeppelin/ui-utils: Shared utility functions
- @openzeppelin/ui-components: UI components
- react: Peer dependency for React hooks and context
- react-dom: Peer dependency for React DOM utilities
- @tanstack/react-query: Peer dependency for data fetching

Development

`bash


Build the package

License

AGPL-3.0