npm package: @justaname.id/react
Description: The **JustaName React SDK** makes it easy to integrate Ethereum Name Service (ENS) functionalities, including subname management, and user authentication via ENS into React applications. It simplifies interacting with ENS off-chain operations while ensuri
Latest version: 0.3.207

# JustaName React SDK

The **JustaName React SDK** makes it easy to integrate Ethereum Name Service (ENS) functionalities, including subname management, and user authentication via ENS into React applications. It simplifies interacting with ENS off-chain operations while ensuring secure and easy integration with your dApps.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
    - [Setup with `JustaNameProvider`](#setup-with-justanameprovider)
    - [Example: Add a Subname](#example-add-a-subname)
- [Hooks](#hooks)
    - [Account and ENS Management](#account-and-ens-management)
    - [Subname Management](#subname-management)
    - [Authentication](#authentication)
    - [Other Hooks](#other-hooks)
---

## Installation

Install the JustaName React SDK using npm or yarn:

```bash
npm install @justaname.id/react

# or

yarn add @justaname.id/react
```

---

## Usage

### Setup with `JustaNameProvider`

To use the JustaName React SDK, wrap your application with the `JustaNameProvider`. This component provides all child components access to the JustaName context, enabling seamless interaction with ENS services.

### Example: Setup with `JustaNameProvider`

```tsx
tsx
'use client';
import { JustaNameProvider } from '@justaname.id/react';
import { configureChains, createClient, WagmiConfig } from 'wagmi';
import { publicProvider } from 'wagmi/providers/public';
import { getDefaultWallets, RainbowKitProvider } from '@rainbow-me/rainbowkit';
import '@rainbow-me/rainbowkit/styles.css';
import { AddSubname } from './AddSubname';

const { wallets } = getDefaultWallets();

const config = getDefaultConfig({
  appName: 'JustaName Console',
  projectId: 'YOUR_PROJECT_ID',
  wallets: [
    ...wallets,
    {
      groupName: 'Other',
      wallets: [argentWallet, trustWallet, ledgerWallet],
    },
  ],
  chains: [mainnet, sepolia],
  ssr: true,
});

const justaNameConfig = {
  networks: [{ chainId: 1, providerUrl: 'https://mainnet.infura.io/v3/YOUR_INFURA_KEY' }],
  ensDomains: [
    { 
      chainId: 1, 
      domain: 'your_ens_domain.eth',
      apiKey: 'your-api-key' // Not recommended for production, use a backend server to protect your API key
    }
  ],
  backendUrl: 'https://your-backend-url.com' // Leave empty for same origin (e.g when using Next.js)
};

export const App = () => {
  return (
    <WagmiConfig client={config}>
      <RainbowKitProvider chains={chains}>
        <JustaNameProvider config={justaNameConfig}>
            <AddSubname />
        </JustaNameProvider>
      </RainbowKitProvider>
    </WagmiConfig>
  );
}

```

---

## Example: Add a Subname

Below is a complete example of a React component where users can claim a subname using the `useAddSubname` hook. It also checks subname availability with `useIsSubnameAvailable`.

```tsx
tsx
Copy code
import { useAddSubname, useIsSubnameAvailable } from '@justaname.id/react';
import { useState } from 'react';
import { useDebounce } from '@uidotdev/usehooks';
import { ConnectButton } from '@rainbow-me/rainbowkit';
import { useAccount } from 'wagmi';

export const AddSubname = () => {
  const { isConnected } = useAccount();
  const [username, setUsername] = useState<string>('');
  const debouncedUsername = useDebounce(username, 500);
  const { isSubnameAvailable } = useIsSubnameAvailable({ 
    username: debouncedUsername 
  });
  const { addSubname } = useAddSubname();

  return (
    <div>
      <h1>Claim your subdomain</h1>
      <ConnectButton />
      <input
        value={username}
        onChange={(e) => setUsername(e.target.value)}
        placeholder="Enter a subdomain"
      />
      <button
        onClick={() => addSubname({ username })}
        disabled={!isSubnameAvailable || !isConnected || !debouncedUsername}
      >
        Claim
      </button>
    </div>
  );
};

```

---

## Hooks

The SDK offers various hooks for managing ENS accounts, subnames, and authentication.

### Account and ENS Management

- **`useAccountEnsNames`**: Fetch ENS names associated with the user's account.
- **`useAddressEnsNames`**: Fetch ENS names for a given Ethereum address.
- **`usePrimaryName`**: Get the primary ENS name of an address.
- **`useAccountInvitations`**: Get pending invitations for the connected account.
- **`useAccountSubnames`**: Fetch all subnames for the connected account.

### Subname Management

- **`useIsSubnameAvailable`**: Check if a subname is available.
- **`useAddSubname`**: Add a new subname off-chain.
- **`useAcceptSubname`**: Accept an invitation for a subname.
- **`useRejectSubname`**: Reject a subname invitation.
- **`useRevokeSubname`**: Revoke an issued subname.
- **`useUpdateSubname`**: Update an ens metadata (off-chain and on-chain).
- **`useSearchSubnames`**: Search for subnames based on given parameters.
- **`useSubname`**: Get the details of a specific subname.
- **`useRecords`**: Fetch records associated with any ENS name.

[//]: # (### mApp Management)

[//]: # ()
[//]: # (- **`useEnabledMApps`**: Get a list of enabled mApps.)

[//]: # (- **`useIsMAppEnabled`**: Check if a specific mApp is enabled.)

[//]: # (- **`useAddMAppPermission`**: Add permission for an mApp.)

[//]: # (- **`useRevokeMAppPermission`**: Revoke an mApp's permission.)

[//]: # (- **`useCanEnableMApps`**: Check if mApps can be enabled for a subname.)

### Authentication

- **`useEnsSignIn`**: Authenticate users with their ENS name.
- **`useEnsSignOut`**: Sign out the connected user.
- **`useEnsAvatar`**: Fetch the avatar of an ENS name.
- **`useEnsAuth`**: Manage authentication state with ENS.

### Other Hooks

- **`useJustaName`**: Access the JustaName context directly.
- **`useMounted`**: Check if the component is mounted.
- **`useMountedAccount`**: Get the mounted account details.
- **`useOffchainResolvers`**: Fetch off-chain resolvers.
- **`useUpdateChanges`**: Check for changes in the ENS metadata before updating.
- **`useUploadMedia`**: Upload media for ENS metadata.

### Contributing
Contributions are welcome! If you have suggestions or find issues, please open an issue or submit a pull request on the GitHub repository.