Skip to Content
🌐 Frontend SDKHooksUI & Utilities

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'
 
function classifyRecipient(input: string) {
  if (looksLikeNickname(input)) {
    return 'nickname' // resolve via useNicknameResolve
  }
  return 'address' // 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

PropertyTypeDescription
colorMode'light' | 'dark'Current color mode.
setColorMode(mode: 'light' | 'dark') => voidSet 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. Returns { open(page, params?), close(), isOpen }; pages are members of the PageKey enum.

import { useOpenPage, PageKey } from '@embarkai/ui-kit'
 
function QuickActions() {
  const { open, close, isOpen } = useOpenPage()
 
  return (
    <div>
      <button onClick={() => open(PageKey.SEND)}>Send</button>
      <button onClick={() => open(PageKey.RECEIVE)}>Receive</button>
      <button onClick={() => open(PageKey.TRANSACTIONS)}>History</button>
      {isOpen && <button onClick={close}>Close</button>}
    </div>
  )
}

Available Pages

PageKeyDescription
SENDSend transaction form.
RECEIVEWallet address and QR code.
BUYOn-ramp / buy crypto flow.
TRANSACTIONSRecent transaction history.
ASSETSToken portfolio.
SETTINGSAccount settings menu.
SECURITYKeyshare status and connected apps.
MANAGE_WALLETLinked profiles and wallet management.
NICKNAME_SETTINGSNickname editor.
CHAINChain selector.
DEVICESLinked devices.
KYCKYC flow.
CONNECT_EXTERNAL_WALLETExternal wallet connection.
AUTHSign-in screen.
LANGUAGESLanguage selector.

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 SDK error message as a string (empty when there is no error). 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">{error}</div>
}

Typed errors with a code are available from the onError Provider callback and the error classes on the Advanced API page.

useNicknameResolve

Resolve an embarkAI nickname to a wallet on a given chain. The hook is declarative: pass the current input and it resolves as the value changes.

import { useState } from 'react'
import { useActiveChainId, useNicknameResolve, looksLikeNickname } from '@embarkai/ui-kit'
 
function NicknameInput() {
  const [input, setInput] = useState('')
  const chainId = useActiveChainId()
  const { resolvedAddress, isResolving, isNotFound, error, isFingerprintVerified } =
    useNicknameResolve(input, { chainId, enabled: looksLikeNickname(input) })
 
  return (
    <div>
      <input
        placeholder="Enter nickname"
        value={input}
        onChange={(e) => setInput(e.target.value)}
      />
      {isResolving && <p>Resolving...</p>}
      {isNotFound && <p>Nickname not found</p>}
      {resolvedAddress && isFingerprintVerified && <p>Address: {resolvedAddress}</p>}
      {error && <p className="error">{error.message}</p>}
    </div>
  )
}

Options

OptionTypeRequiredDescription
chainIdnumberYesChain to resolve the nickname on.
enabledbooleanNoPause resolution (e.g. while the input is not nickname-shaped).

Return Value

PropertyTypeDescription
dataNicknameResolution | undefinedRaw result: handle, owner, fingerprint, resolvedTarget: { chainId, wallet } | null, availableTargets, isFrozen.
resolvedAddressstring | nullWallet address for the requested chain.
isLoading / isResolvingbooleanQuery state.
isNotFoundbooleanNickname does not exist.
isWalletNotSetupbooleanNickname exists but has no wallet on this chain.
isFrozenbooleanNickname is frozen.
isFingerprintVerifiedbooleanThe owner fingerprint matched the locally computed one.
fingerprintVerificationFingerprintVerificationResult | nullDetails of the fingerprint check.
isError / errorboolean / Error | nullFailure state.

useProviderConfig

Read and update the Provider configuration at runtime without remounting. config is a ref (RefObject<ProviderConfig>): reading it does not subscribe to changes. updateConfig takes whole sections, so spread the current one.

import { useProviderConfig } from '@embarkai/ui-kit'
 
function ChainSwitcher() {
  const { config, updateConfig } = useProviderConfig()
 
  return (
    <select
      defaultValue={config.current.network.chainId}
      onChange={(e) =>
        updateConfig({
          network: { ...config.current.network, chainId: Number(e.target.value) },
        })
      }
    >
      <option value={994873017}>Lumia Mainnet</option>
      <option value={2030232745}>Lumia Testnet</option>
    </select>
  )
}

The chain the user is currently on is useActiveChainId(); config.current.network.chainId is the configured default.

Next Steps

Last updated on
External WalletComponents