Address Input

Introduction

AddressInput is a comprehensive input component for Polkadot and Ethereum addresses with real-time validation and identity lookup.

Features

• ✅ Address Validation: Real-time validation for SS58 (Polkadot) and Ethereum addresses
• ✅ Identity Lookup: Automatic Polkadot identity resolution using PAPI
• ✅ Identity Search: Search by display name; results only include validated identities
• ✅ Visual Feedback: Color-coded validation states and loading indicators
• ✅ Flexible Formats: Support for SS58, Ethereum, or both address types
• ✅ TypeScript: Full type safety with comprehensive interfaces
• ✅ Customizable: Optional identicon, truncation, and styling options

Installation

npx polkadot-ui@latest add address-input

The Address Input component additionaly depends on tanstack react-query to fetch data. So you will need to wrap your app in a QueryClientProvider.

import { QueryClient, QueryClientProvider } from "@tanstack/react-query"

const queryClient = new QueryClient()

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <QueryClientProvider client={queryClient}>
    //... 
  </QueryClientProvider>
}

Usage

Props

Validation States

The component shows different visual states:

• Valid: Green border with checkmark
• Invalid: Red border with error message
• Loading: Spinner while checking identity
• Disconnected: Warning when chain not connected

Identity Lookup

When withIdentityLookup is enabled:

1. Valid SS58 addresses trigger identity lookup
2. Displays identity name if found
3. Shows verification status
4. Includes "PAPI" badge to indicate API source

Identity Search

• When withIdentitySearch is enabled (default), typing at least 3 characters shows a dropdown of identities matching the display name on the selected identityChain.
• withIdentitySearch controls the display-name search independently of withIdentityLookup (you can enable one without the other).
• The search results only include identities that are validated/verified.
• Selecting a result fills the address field with the corresponding account and triggers onIdentitySelected.
• Keyboard navigation is supported (Arrow keys, Enter, Escape; Tab cycles results).

Multi-Chain Identity Support

The identityChain prop allows you to specify which chain to use for identity lookups. This is particularly useful in multi-chain environments where different chains may have different identity registries:

• paseoPeople (default in adapters): Paseo People chain for testnet identities
• kusamaPeople: Kusama People chain for Kusama identities
• polkadotPeople: Polkadot People chain for mainnet identities

The type ChainIdWithIdentity ensures only chains with Identity pallet support can be used.

Identicon Support

The component automatically displays the appropriate identicon based on address type:

Polkadot/Substrate Addresses (SS58)

Different visual themes available via the identiconTheme prop:

• polkadot (default): Official Polkadot-style identicon with geometric patterns
• substrate: Alternative Substrate-themed identicon style
• beachball: Colorful circular pattern resembling a beach ball
• jdenticon: JDenticon style with geometric shapes and patterns

Ethereum Addresses

• Ethereum Identicons: Automatically uses the jdenticon theme for ETH addresses
• Ethereum addresses are converted to SS58 format for consistent identicon generation
• Uses the same @polkadot/react-identicon library with specialized handling for Ethereum

The component intelligently switches between identicon themes based on address type, providing a consistent visual experience.