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

# useIdentity

> React hooks for ZKScore identity management

## useIdentity

Get identity information for an Ethereum address.

```tsx theme={null}
import { useIdentity } from '@zkscore/react';

function IdentityCard({ address }: { address: string }) {
  const { identity, loading, error } = useIdentity(address);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!identity) return <div>No identity found</div>;

  return (
    <div>
      <h2>{identity.username}</h2>
      <p>Token ID: {identity.tokenId}</p>
      <p>Minted: {new Date(identity.mintedAt).toLocaleDateString()}</p>
    </div>
  );
}
```

### Parameters

<ParamField path="address" type="string" required>
  Ethereum address to query
</ParamField>

<ParamField path="options" type="object">
  Query options

  <Expandable title="Options">
    <ParamField path="enabled" type="boolean">
      Enable/disable the query
    </ParamField>

    <ParamField path="refreshInterval" type="number">
      Auto-refresh interval in ms
    </ParamField>
  </Expandable>
</ParamField>

### Returns

<ResponseField name="identity" type="Identity | null">
  The identity object or null if not found
</ResponseField>

<ResponseField name="loading" type="boolean">
  Loading state
</ResponseField>

<ResponseField name="error" type="Error | null">
  Error object if request failed
</ResponseField>

<ResponseField name="refetch" type="function">
  Manually refetch identity
</ResponseField>

## useMintIdentity

Mint a new ZKScore identity.

```tsx theme={null}
import { useMintIdentity } from '@zkscore/react';
import { useState } from 'react';

function MintIdentityForm({ address }: { address: string }) {
  const [username, setUsername] = useState('');
  const { mutate, loading, error, data } = useMintIdentity({
    onSuccess: (identity) => {
      console.log('Identity minted:', identity);
    },
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    mutate({ address, username });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={username}
        onChange={(e) => setUsername(e.target.value)}
        placeholder="Choose username"
        required
      />
      <button type="submit" disabled={loading}>
        {loading ? 'Minting...' : 'Mint Identity'}
      </button>
      {error && <p className="error">{error.message}</p>}
      {data && <p className="success">Identity created: {data.username}</p>}
    </form>
  );
}
```

### Parameters

<ParamField path="options" type="object">
  Mutation options

  <Expandable title="Options">
    <ParamField path="onSuccess" type="function">
      Callback on successful mint
    </ParamField>

    <ParamField path="onError" type="function">
      Callback on error
    </ParamField>
  </Expandable>
</ParamField>

### Returns

<ResponseField name="mutate" type="function">
  Function to trigger the mint
</ResponseField>

<ResponseField name="loading" type="boolean">
  Loading state
</ResponseField>

<ResponseField name="error" type="Error | null">
  Error object if mint failed
</ResponseField>

<ResponseField name="data" type="Identity | null">
  Minted identity data
</ResponseField>

## useCheckUsername

Check if a username is available.

```tsx theme={null}
import { useCheckUsername } from '@zkscore/react';
import { useState, useEffect } from 'react';

function UsernameInput() {
  const [username, setUsername] = useState('');
  const { check, available, checking } = useCheckUsername();

  useEffect(() => {
    if (username.length >= 3) {
      check(username);
    }
  }, [username]);

  return (
    <div>
      <input
        value={username}
        onChange={(e) => setUsername(e.target.value)}
        placeholder="Username"
      />
      {checking && <span>Checking...</span>}
      {!checking && username.length >= 3 && (
        <span className={available ? 'success' : 'error'}>
          {available ? '✓ Available' : '✗ Taken'}
        </span>
      )}
    </div>
  );
}
```

### Returns

<ResponseField name="check" type="function">
  Function to check username availability
</ResponseField>

<ResponseField name="available" type="boolean | null">
  Whether username is available
</ResponseField>

<ResponseField name="checking" type="boolean">
  Loading state
</ResponseField>

## useActivateIdentity

Activate a minted identity.

```tsx theme={null}
import { useActivateIdentity } from '@zkscore/react';

function ActivateButton({ tokenId }: { tokenId: string }) {
  const { mutate, loading, error } = useActivateIdentity({
    onSuccess: () => {
      console.log('Identity activated!');
    },
  });

  return (
    <div>
      <button onClick={() => mutate({ tokenId })} disabled={loading}>
        {loading ? 'Activating...' : 'Activate Identity'}
      </button>
      {error && <p className="error">{error.message}</p>}
    </div>
  );
}
```

## Advanced Examples

### Complete Identity Flow

```tsx theme={null}
import { useIdentity, useMintIdentity, useCheckUsername } from '@zkscore/react';
import { useState } from 'react';

function IdentityManager({ address }: { address: string }) {
  const { identity, loading: identityLoading } = useIdentity(address);
  const [username, setUsername] = useState('');
  const { check, available } = useCheckUsername();
  const { mutate: mint, loading: minting } = useMintIdentity({
    onSuccess: () => setUsername(''),
  });

  if (identityLoading) return <div>Loading...</div>;

  if (identity) {
    return (
      <div>
        <h2>Welcome, {identity.username}!</h2>
        <p>Your ZKScore ID is active</p>
      </div>
    );
  }

  return (
    <div>
      <h2>Create Your ZKScore Identity</h2>
      <input
        value={username}
        onChange={(e) => {
          setUsername(e.target.value);
          check(e.target.value);
        }}
        placeholder="Choose username"
      />
      {available !== null && (
        <p className={available ? 'success' : 'error'}>
          {available ? 'Username available' : 'Username taken'}
        </p>
      )}
      <button
        onClick={() => mint({ address, username })}
        disabled={!available || minting}
      >
        {minting ? 'Creating...' : 'Create Identity'}
      </button>
    </div>
  );
}
```

### Identity with Avatar

```tsx theme={null}
import { useIdentity } from '@zkscore/react';

function IdentityAvatar({ address }: { address: string }) {
  const { identity } = useIdentity(address);

  if (!identity) return <div className="avatar-placeholder" />;

  return (
    <div className="identity-avatar">
      <img
        src={`https://api.onzks.com/avatar/${identity.id}`}
        alt={identity.username}
      />
      <span>{identity.username}</span>
    </div>
  );
}
```

### Batch Identity Loading

```tsx theme={null}
import { useIdentities } from '@zkscore/react';

function UserList({ addresses }: { addresses: string[] }) {
  const { identities, loading } = useIdentities(addresses);

  if (loading) return <div>Loading identities...</div>;

  return (
    <ul>
      {identities.map((identity, i) => (
        <li key={i}>
          {identity ? identity.username : addresses[i]}
        </li>
      ))}
    </ul>
  );
}
```

## TypeScript Types

```typescript theme={null}
interface Identity {
  id: string;
  username: string;
  address: string;
  tokenId: string;
  mintedAt: string;
  activatedAt?: string;
  active: boolean;
}

interface MintParams {
  address: string;
  username: string;
}

interface ActivateParams {
  tokenId: string;
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="useScore" icon="chart-line" href="/sdk/react/use-score">
    Learn about score hooks
  </Card>

  <Card title="useAchievements" icon="trophy" href="/sdk/react/use-achievements">
    Achievement hooks
  </Card>

  <Card title="Identity API" icon="code" href="/api-reference/identity/get-identity">
    Identity API reference
  </Card>

  <Card title="Concepts" icon="book" href="/concepts/identity">
    Learn about identities
  </Card>
</CardGroup>