Skip to main content

useIdentity

Get identity information for an Ethereum address.
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

address
string
required
Ethereum address to query
options
object
Query options

Returns

identity
Identity | null
The identity object or null if not found
loading
boolean
Loading state
error
Error | null
Error object if request failed
refetch
function
Manually refetch identity

useMintIdentity

Mint a new ZKScore identity.
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

options
object
Mutation options

Returns

mutate
function
Function to trigger the mint
loading
boolean
Loading state
error
Error | null
Error object if mint failed
data
Identity | null
Minted identity data

useCheckUsername

Check if a username is available.
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

check
function
Function to check username availability
available
boolean | null
Whether username is available
checking
boolean
Loading state

useActivateIdentity

Activate a minted identity.
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

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

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

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

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