> ## Documentation Index
> Fetch the complete documentation index at: https://docs.initia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# useUsernameQuery

## Overview

* React Query hook that fetches the Initia (`.init`) username for a provided
  address, or for the connected address when no argument is passed.
* Automatically re-runs when the target address changes.
* Exposes standard React Query state (`isLoading`, `error`, etc.).

## Prerequisites

* Must be rendered within `InterwovenKitProvider`.
* Must be used within a React Query `QueryClientProvider`.
* Must be used within a wagmi `WagmiProvider`.
* Client-only (no SSR): Put this in a `use client` provider tree, or use a
  dynamic import in Next.js.

## Quickstart

### Connected Wallet

Call `useUsernameQuery()` with no arguments to resolve the username for the
currently connected wallet.

```tsx theme={null}
'use client'

import { useUsernameQuery } from '@initia/interwovenkit-react'

function Username() {
  const { data, isLoading } = useUsernameQuery()
  if (isLoading) return <span>Loading…</span>
  return <span>{data ?? 'No username'}</span>
}
```

### Specific Address

Pass an address to resolve the username for that address instead of the
connected wallet.

```tsx theme={null}
'use client'

import { useUsernameQuery } from '@initia/interwovenkit-react'

function SenderUsername({ address }: { address: string }) {
  const { data } = useUsernameQuery(address)
  return <span>{data ?? address}</span>
}
```

<Note>
  These examples assume providers are already set up. For complete setup
  configurations, see [Provider Setup](../setup/providers).
</Note>

## Return Value

```ts theme={null}
function useUsernameQuery(address?: string): UseQueryResult<string | null>
```

Returns a React Query `UseQueryResult<string | null>` object. The `data`
property is:

* `string` when a username exists (ends with `.init`)
* `null` when no username exists or the address is invalid
* `undefined` before the query has produced a value or when the query is
  disabled (for example, when neither an explicit address nor a connected wallet
  address is available)

Type `UseQueryResult` is from `@tanstack/react-query`.

## Notes

* If `address` is omitted, the hook falls back to the connected address from
  `useAddress()`.