useNetwork

The useNetwork hook/composable provides access to network-related state and methods from the WalletManager. It enables applications to switch between networks and customize node configurations at runtime.

Basic usage

React
Vue
Solid
Svelte

import { useNetwork } from '@txnlab/use-wallet-react'

function NetworkStatus() {
  const { activeNetwork, activeNetworkConfig } = useNetwork()

  return (
    <div>
      <div>Network: {activeNetwork}</div>
      <div>Node: {activeNetworkConfig.algod.baseServer}</div>
    </div>
  )
}

<script setup>
import { useNetwork } from '@txnlab/use-wallet-vue'

const { activeNetwork, activeNetworkConfig } = useNetwork()
</script>

<template>
  <div>
    <div>Network: {{ activeNetwork }}</div>
    <div>Node: {{ activeNetworkConfig.algod.baseServer }}</div>
  </div>
</template>

import { useNetwork } from '@txnlab/use-wallet-solid'

function NetworkStatus() {
  const { activeNetwork, activeNetworkConfig } = useNetwork()

  return (
    <div>
      <div>Network: {activeNetwork()}</div>
      <div>Node: {activeNetworkConfig().algod.baseServer}</div>
    </div>
  )
}

<script lang="ts">
import { useNetwork } from '@txnlab/use-wallet-svelte'

const { activeNetwork, activeNetworkConfig } = useNetwork()
</script>

<div>
  <div>Network: {activeNetwork.current}</div>
  <div>Node: {activeNetworkConfig.current.algod.baseServer}</div>
</div>

Return values

State properties

activeNetwork

string

required

Currently active network ID (e.g., 'mainnet', 'testnet', 'localnet')

networkConfig

Record<string, NetworkConfig>

required

Complete network configuration object containing all configured networks

Show NetworkConfig interface

algod

AlgodConfig

required

Algod node configuration

interface AlgodConfig {
  token: string | algosdk.AlgodTokenHeader | algosdk.CustomTokenHeader
  baseServer: string
  port?: string | number
  headers?: Record<string, string>
}

genesisHash

string

Optional genesis hash for network validation

genesisId

string

Optional genesis ID for network identification

isTestnet

boolean

Whether this is a testnet (affects dispenser integration)

caipChainId

string

Optional CAIP-2 chain identifier

activeNetworkConfig

NetworkConfig

required

Configuration object for the currently active network

Methods

setActiveNetwork

function

required

Switch to a different network.

setActiveNetwork(networkId: NetworkId | string): Promise<void>

Show Details

networkId

NetworkId | string

required

Network identifier (e.g., NetworkId.MAINNET, 'testnet', or a custom network ID)

Behavior:

Creates a new Algod client for the target network
Updates the active network in the store
Persists the selection to local storage
Maintains active wallet sessions (if supported by the wallet)

Throws: Error if the network ID is not found in the configuration

updateAlgodConfig

function

required

Update the Algod client configuration for a specific network.

updateAlgodConfig(networkId: string, config: Partial<AlgodConfig>): void

Show Details

networkId

string

required

Network identifier to update

config

Partial<AlgodConfig>

required

Partial configuration to merge with existing settings

interface AlgodConfig {
  token?: string | algosdk.AlgodTokenHeader | algosdk.CustomTokenHeader
  baseServer?: string
  port?: string | number
  headers?: Record<string, string>
}

Behavior:

Merges the new configuration with existing settings
Creates a new Algod client if updating the active network
Persists the configuration to local storage

resetNetworkConfig

function

required

Reset a network’s configuration to its default values.

resetNetworkConfig(networkId: string): void

Show Details

networkId

string

required

Network identifier to reset

Behavior:

Restores the original configuration for the specified network
Creates a new Algod client if resetting the active network
Removes any custom configuration from local storage

Framework-specific details

React

State access
Switching networks

React provides state directly as properties:

const { activeNetwork, networkConfig } = useNetwork()

// Direct property access
console.log(activeNetwork) // 'testnet'
console.log(networkConfig['mainnet'].algod.baseServer)

import { useNetwork, NetworkId } from '@txnlab/use-wallet-react'

function NetworkSwitcher() {
  const { activeNetwork, setActiveNetwork } = useNetwork()

  const handleSwitch = async (networkId: string) => {
    try {
      await setActiveNetwork(networkId)
    } catch (error) {
      console.error('Network switch failed:', error)
    }
  }

  return (
    <div>
      <button onClick={() => handleSwitch(NetworkId.MAINNET)}>
        Mainnet
      </button>
      <button onClick={() => handleSwitch(NetworkId.TESTNET)}>
        Testnet
      </button>
    </div>
  )
}

Vue

State access
Switching networks

Vue returns reactive refs that auto-unwrap in templates:

<script setup>
const { activeNetwork, networkConfig } = useNetwork()

// Access .value in script
console.log(activeNetwork.value) // 'testnet'
console.log(networkConfig['mainnet'].algod.baseServer)
</script>

<template>
  <!-- Auto-unwrapped in templates -->
  <div>{{ activeNetwork }}</div>
</template>

<script setup lang="ts">
import { useNetwork, NetworkId } from '@txnlab/use-wallet-vue'

const { activeNetwork, setActiveNetwork } = useNetwork()

const handleSwitch = async (networkId: string) => {
  try {
    await setActiveNetwork(networkId)
  } catch (error) {
    console.error('Network switch failed:', error)
  }
}
</script>

<template>
  <div>
    <button @click="handleSwitch(NetworkId.MAINNET)">
      Mainnet
    </button>
    <button @click="handleSwitch(NetworkId.TESTNET)">
      Testnet
    </button>
  </div>
</template>

Solid

State access
Switching networks

Solid uses getter functions for reactive state:

const { activeNetwork, networkConfig } = useNetwork()

// Access via function call
console.log(activeNetwork()) // 'testnet'
console.log(networkConfig()['mainnet'].algod.baseServer)

import { useNetwork, NetworkId } from '@txnlab/use-wallet-solid'

function NetworkSwitcher() {
  const { activeNetwork, setActiveNetwork } = useNetwork()

  const handleSwitch = async (networkId: string) => {
    try {
      await setActiveNetwork(networkId)
    } catch (error) {
      console.error('Network switch failed:', error)
    }
  }

  return (
    <div>
      <button onClick={() => handleSwitch(NetworkId.MAINNET)}>
        Mainnet
      </button>
      <button onClick={() => handleSwitch(NetworkId.TESTNET)}>
        Testnet
      </button>
    </div>
  )
}

Svelte

State access
Switching networks

Svelte uses .current to access reactive values:

<script lang="ts">
const { activeNetwork, networkConfig } = useNetwork()

// Access via .current property
console.log(activeNetwork.current) // 'testnet'
console.log(networkConfig['mainnet'].algod.baseServer)
</script>

<div>{activeNetwork.current}</div>

<script lang="ts">
import { useNetwork, NetworkId } from '@txnlab/use-wallet-svelte'

const { activeNetwork, setActiveNetwork } = useNetwork()

const handleSwitch = async (networkId: string) => {
  try {
    await setActiveNetwork(networkId)
  } catch (error) {
    console.error('Network switch failed:', error)
  }
}
</script>

<div>
  <button onclick={() => handleSwitch(NetworkId.MAINNET)}>
    Mainnet
  </button>
  <button onclick={() => handleSwitch(NetworkId.TESTNET)}>
    Testnet
  </button>
</div>

Common use cases

Switching networks

import { useNetwork, NetworkId } from '@txnlab/use-wallet-[framework]'

const { setActiveNetwork } = useNetwork()

try {
  await setActiveNetwork(NetworkId.MAINNET)
} catch (error) {
  console.error('Failed to switch network:', error)
}

Updating node configuration

import { useNetwork } from '@txnlab/use-wallet-[framework]'

const { updateAlgodConfig } = useNetwork()

// Point testnet to a custom node
updateAlgodConfig('testnet', {
  baseServer: 'https://my-custom-node.example.com',
  port: 443,
  token: 'my-api-token'
})

Resetting to defaults

import { useNetwork } from '@txnlab/use-wallet-[framework]'

const { resetNetworkConfig } = useNetwork()

// Reset testnet to default configuration
resetNetworkConfig('testnet')

Custom network configuration

// During WalletManager initialization
const manager = new WalletManager({
  wallets: [WalletId.PERA],
  network: 'custom-network',
  networkConfig: {
    'custom-network': {
      algod: {
        token: 'custom-token',
        baseServer: 'https://custom-node.example.com',
        port: 443
      },
      isTestnet: true
    }
  }
})

// Later, switch to custom network
const { setActiveNetwork } = useNetwork()
await setActiveNetwork('custom-network')

Network identifiers

Built-in network IDs available via the NetworkId enum:

import { NetworkId } from '@txnlab/use-wallet'

NetworkId.MAINNET   // 'mainnet'
NetworkId.TESTNET   // 'testnet'
NetworkId.BETANET   // 'betanet'
NetworkId.LOCALNET  // 'localnet'

You can also use custom string identifiers for custom networks.

Error handling

Network operations may throw errors in these situations:

try {
  await setActiveNetwork('invalid-network')
} catch (error) {
  // Error: Network "invalid-network" not found in network configuration
}

try {
  updateAlgodConfig('testnet', {
    baseServer: '' // Invalid empty server
  })
} catch (error) {
  // Error: Invalid configuration
}

TypeScript support

Full TypeScript definitions are available:

import type {
  NetworkId,
  NetworkConfig,
  AlgodConfig
} from '@txnlab/use-wallet-react' // or vue/solid/svelte

// NetworkConfig type
interface NetworkConfig {
  algod: AlgodConfig
  genesisHash?: string
  genesisId?: string
  isTestnet?: boolean
  caipChainId?: string
}

// AlgodConfig type
interface AlgodConfig {
  token: string | algosdk.AlgodTokenHeader | algosdk.CustomTokenHeader
  baseServer: string
  port?: string | number
  headers?: Record<string, string>
}

Core API

Framework Hooks

Wallet Providers

Security

Basic usage

Return values

State properties

Methods

Framework-specific details

React

Vue

Solid

Svelte

Common use cases

Switching networks

Updating node configuration

Resetting to defaults

Custom network configuration

Network identifiers

Error handling

TypeScript support

Build docs developers (and LLMs) love

Core API

Framework Hooks

Wallet Providers

Security

​Basic usage

​Return values

​State properties

​Methods

​Framework-specific details

​React

​Vue

​Solid

​Svelte

​Common use cases

​Switching networks

​Updating node configuration

​Resetting to defaults

​Custom network configuration

​Network identifiers

​Error handling

​TypeScript support

Build docs developers (and LLMs) love

Basic usage

Return values

State properties

Methods

Framework-specific details

React

Vue

Solid

Svelte

Common use cases

Switching networks

Updating node configuration

Resetting to defaults

Custom network configuration

Network identifiers

Error handling

TypeScript support