dot-ui

Getting Started

Introduction

Dot UI is a comprehensive component library for building Polkadot applications. Think of it as shadcn/ui for Web3 - a collection of beautifully designed, accessible components specifically tailored for the Polkadot ecosystem.

Key Features

  • ⚡ Zero-config setup - Automatic API and provider configuration
  • 🎯 Production-ready - Type-safe components with proper error handling
  • 🔄 Multi-library support - Works with both polkadot-api (PAPI) and Dedot
  • 🔧 Framework agnostic - Next.js, Vite, TypeScript out-of-the-box
  • 🎨 Fully customizable - Built on shadcn/ui, you have full control over the design, as components are added to your codebase
  • 📱 Responsive - Mobile-first components that work everywhere

Quick Start

The fastest way to get started is to add a component to your existing project:

npx polka-ui@latest add address-input

This single command will:

  • Install the component and all dependencies
  • Set up Polkadot API configuration
  • Configure providers and chain connections
  • Generate TypeScript types

Then use it immediately with the self-contained version:

import { AddressInputWithProvider } from "@/components/ui/address-input"
import { useState } from "react"

export default function MyApp() {
  const [address, setAddress] = useState("")

  return (
    <div className="p-8">
      <h1>My Polkadot App</h1>
      <AddressInputWithProvider 
        value={address} 
        onChange={setAddress}
        placeholder="Enter Polkadot address..."
        format="both" // Supports both SS58 and Ethereum
        withIdentityLookup={true} // Automatic identity resolution
        chainId="paseo" // Specify chain
      />
      <p>Selected address: {address}</p>
    </div>
  )
}

Available Components

Loading components...

Installation

Option 1: Add to Existing Project

If you have an existing Next.js or Vite project:

# Add any component - the CLI will set up everything needed
npx polka-ui@latest add address-input

Option 2: Create New Project

Start from scratch with a fully configured project:

# Create and configure new project
npx polka-ui@latest init

# Add components
npx polka-ui@latest add address-input
npx polka-ui@latest add block-number

Option 3: Package Managers

Use your preferred package manager:

# Using pnpm (recommended)
pnpm dlx polka-ui@latest add address-input

# Using bun
bunx polka-ui@latest add address-input

# Using yarn
npx polka-ui@latest add address-input

Add Your First Component

For demo purposes, we provider a WithProvider version of each component that is used to show the component in action. For production applications with multiple components, set up providers at the root level for better performance and shared state:

// app/layout.tsx (Next.js) or main.tsx (Vite)
import { PolkadotProvider } from "@/lib/providers/papi-provider"
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: false,
      staleTime: 5 * 60 * 1000, // 5 minutes
    },
  },
})

export default function RootLayout({ children }) {
  return (
    <PolkadotProvider defaultChain="paseo">
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </PolkadotProvider>
  )
}

Then use components directly without individual providers:

// components/my-component.tsx
import { AddressInput } from "@/components/ui/address-input"
import { useState } from "react"

export default function MyComponent() {
  const [address, setAddress] = useState("")

  return (
    <div className="space-y-4">
      <AddressInput 
        value={address} 
        onChange={setAddress}
        placeholder="Enter Polkadot address..."
        format="both" // Supports both SS58 and Ethereum
        withIdentityLookup={true} // Automatic identity resolution
      />
      {address && <p>Selected: {address}</p>}
    </div>
  )
}

Key Concepts

Providers

Dot UI uses React Context providers to manage blockchain connections:

// Automatically added by the CLI
import { PolkadotProvider } from "@/lib/providers/papi-provider"

export default function RootLayout({ children }) {
  return (
    <PolkadotProvider defaultChain="paseo">
      {children}
    </PolkadotProvider>
  )
}

Hooks

Access blockchain data with type-safe hooks:

import { usePapi, usePolkadotApi } from "@/lib/providers/papi-provider"

function MyComponent() {
  const { currentChain, isLoading, error } = usePapi()
  const peopleApi = usePolkadotApi('paseo_people')
  
  // Your component logic
}

Multi-Chain Support

Components work across multiple Polkadot chains:

const { setApi, availableChains } = usePapi()

// Switch between chains
setApi('paseo')           // Paseo testnet
setApi('paseo_people')    // People chain

Supported Frameworks

Dot UI works with modern React frameworks:

  • ✅ Next.js 14+ (App Router & Pages Router)
  • ✅ Vite + React with TypeScript
  • ✅ Create React App (CRA)

Supported Libraries

Choose your preferred Polkadot library:

  • 🔥 polkadot-api (PAPI) - Modern, lightweight, type-safe
  • 🔄 Dedot - Alternative with different approach

The CLI automatically detects which library you're using and installs the appropriate version.

Configuration

Chains

Configure supported chains in your project:

// lib/config.papi.ts
export const polkadotConfig = {
  chains: {
    paseo: {
      endpoints: ["wss://sys.ibp.network/paseo"],
      displayName: "Paseo Relay Chain",
      descriptor: paseo, // Auto-generated types
    },
    paseo_people: {
      endpoints: ["wss://sys.ibp.network/people-paseo"],
      displayName: "Paseo People",
      descriptor: paseo_people,
    },
  },
  defaultChain: "paseo",
}

Theming

Built on shadcn/ui's theming system:

/* Your existing CSS variables work */
:root {
  --primary: 222.2 84% 4.9%;
  --background: 0 0% 100%;
  /* ... */
}

Next Steps

Explore Components

Learn the CLI

Join the Community

Need Help?

Ready to build your Polkadot application? Start by adding your first component:

npx polka-ui@latest add address-input

CLI

CLI is the command line interface for the Polkadot UI Initiative.