UI & Utilities

Utility hooks for color mode, viewport detection, chain selection, error handling, and UI navigation.

These hooks provide access to UI state and SDK utilities that are useful across your application.

Import


import {
  useColorMode,
  useIsMobileView,
  useActiveChainId,
  useOpenPage,
  useIFrameReady,
  useError,
  useNicknameResolve,
  looksLikeNickname,
  useProviderConfig,
  wagmiConfig,
  getExplorerUrl,
  useBlockscoutAssets,
} from '@embarkai/ui-kit'

This guide covers the hook APIs. Several non-hook helpers are also exported:

looksLikeNickname(input: string): boolean — cheap client-side check that returns true for nickname-shaped input. Use it to gate calls to useNicknameResolve or route between address and nickname branches.
wagmiConfig — the wagmi Config instance used internally by Provider. Import it when you need the same wagmi state outside EmbarkAI components (e.g. to call wagmi actions directly, or to share with another wagmi-aware library).
getExplorerUrl(): string — resolves the block explorer URL for the currently active chain (e.g. https://explorer.lumia.org). Uses the built-in chain config.


import { looksLikeNickname } from '@embarkai/ui-kit'
 
if (looksLikeNickname(input)) {
  // resolve via useNicknameResolve
} else {
  // treat as raw 0x… address
}

useColorMode

Get and set the current color mode. The SDK supports 'light' and 'dark' themes.


import { useColorMode } from '@embarkai/ui-kit'
 
function ThemeToggle() {
  const { colorMode, setColorMode } = useColorMode()
 
  return (
    <button onClick={() => setColorMode(colorMode === 'light' ? 'dark' : 'light')}>
      {colorMode === 'light' ? '🌙' : '☀️'}
    </button>
  )
}

Return Value

Property	Type	Description
`colorMode`	`'light' \| 'dark'`	Current color mode.
`setColorMode`	`(mode: 'light' \| 'dark') => void`	Set the color mode.

useIsMobileView

Returns true when the viewport width is below the mobile breakpoint (default: 768px). Useful for responsive layouts.


import { useIsMobileView } from '@embarkai/ui-kit'
 
function ResponsiveLayout({ children }: { children: React.ReactNode }) {
  const isMobile = useIsMobileView()
 
  return (
    <div className={isMobile ? 'mobile-layout' : 'desktop-layout'}>
      {children}
    </div>
  )
}

useActiveChainId

Returns the currently active chain ID. Updates when the user switches chains.


import { useActiveChainId } from '@embarkai/ui-kit'
 
function ChainIndicator() {
  const chainId = useActiveChainId()
 
  const chainNames: Record<number, string> = {
    1: 'Ethereum',
    56: 'BSC',
    42161: 'Arbitrum',
    8453: 'Base',
    994873017: 'Lumia',
  }
 
  return <span>Chain: {chainNames[chainId] ?? `Unknown (${chainId})`}</span>
}

useOpenPage

Programmatically open internal SDK UI pages such as send, receive, or transaction history.


import { useOpenPage } from '@embarkai/ui-kit'
 
function QuickActions() {
  const openPage = useOpenPage()
 
  return (
    <div>
      <button onClick={() => openPage('send')}>Send</button>
      <button onClick={() => openPage('receive')}>Receive</button>
      <button onClick={() => openPage('history')}>History</button>
    </div>
  )
}

Available Pages

Page	Description
`'send'`	Open the send transaction form.
`'receive'`	Show the wallet address and QR code.
`'history'`	Display recent transaction history.

useIFrameReady

Returns true once the secure MPC iframe has loaded. The iframe handles key generation and signing operations. You should wait for it before triggering any signing operations.


import { useIFrameReady } from '@embarkai/ui-kit'
 
function SigningGuard({ children }: { children: React.ReactNode }) {
  const iframeReady = useIFrameReady()
 
  if (!iframeReady) return <p>Initializing secure environment...</p>
 
  return <>{children}</>
}

useError

Returns the most recent error from the SDK. Useful for global error banners or logging.


import { useError } from '@embarkai/ui-kit'
 
function ErrorBanner() {
  const error = useError()
 
  if (!error) return null
 
  return (
    <div className="error-banner">
      <p>{error.message}</p>
      <p className="text-sm">{error.code}</p>
    </div>
  )
}

Return Value

Property	Type	Description
`message`	`string`	Human-readable error description.
`code`	`string`	Error code (e.g., `'SESSION_EXPIRED'`, `'BUNDLER_ERROR'`).

useNicknameResolve

Resolve a human-readable nickname to a wallet address. Supports EmbarkAI nicknames and ENS names.


import { useNicknameResolve } from '@embarkai/ui-kit'
 
function NicknameInput() {
  const { resolve, address, isLoading, error } = useNicknameResolve()
 
  return (
    <div>
      <input
        placeholder="Enter nickname or ENS"
        onChange={(e) => resolve(e.target.value)}
      />
      {isLoading && <p>Resolving...</p>}
      {address && <p>Address: {address}</p>}
      {error && <p className="error">{error}</p>}
    </div>
  )
}

Return Value

Property	Type	Description
`resolve`	`(name: string) => void`	Trigger resolution of a nickname.
`address`	`0x${string}` \| null	Resolved address, or `null` if not found.
`isLoading`	`boolean`	`true` while resolving.
`error`	`string \| null`	Error message if resolution failed.

useProviderConfig

Read and update the Provider configuration at runtime. Useful for switching chains or updating settings without remounting.


import { useProviderConfig } from '@embarkai/ui-kit'
 
function ChainSwitcher() {
  const { config, updateConfig } = useProviderConfig()
 
  return (
    <select
      value={config.chainId}
      onChange={(e) => updateConfig({ chainId: Number(e.target.value) })}
    >
      <option value={994873017}>Lumia</option>
      <option value={1}>Ethereum</option>
      <option value={56}>BSC</option>
      <option value={42161}>Arbitrum</option>
      <option value={8453}>Base</option>
    </select>
  )
}

Next Steps

Hooks Overview — all available hooks
Theming — customize colors and dark mode
Provider — full provider configuration reference