Oviato Connect

Components Reference

Pre-built UI components for Oviato Connect

@oviato/connect provides pre-built React components for authentication and wallet management. These components handle the complex UI and authentication flow, allowing you to integrate Oviato quickly.

Connect

A pre-built authentication form with username input and availability checking. This is the easiest way to add Oviato authentication to your app.

Basic Usage

import { Connect } from '@oviato/connect/client';

function MyComponent() {
  return (
    <Connect
      callback={(data) => {
        console.log('Connected:', data.address);
        console.log('Public Key:', data.publicKey);
      }}
    />
  );
}

Props

interface ConnectProps {
  /** Callback fired on successful authentication */
  callback?: (data: {
    address: string;
    publicKey: string;
  }) => void;
}

Features

The Connect component includes:

Username input with real-time validation
Availability checking - verifies username is not taken
Auto login/register - automatically determines if user is new or existing
Loading states - shows feedback during authentication
Built-in styling - works out of the box with minimal setup

Complete Example

'use client';

import { Connect } from '@oviato/connect/client';
import { useOviConnect } from '@oviato/connect/client';

export default function AuthPage() {
  const { session } = useOviConnect();

  if (session) {
    return (
      <div>
        <p>Already connected as {session.address}</p>
      </div>
    );
  }

  return (
    <div className="auth-container">
      <h1>Connect Your Wallet</h1>
      <Connect
        callback={(data) => {
          console.log('Successfully connected!');
          console.log('Address:', data.address);
          // Redirect or update UI
          window.location.href = '/dashboard';
        }}
      />
    </div>
  );
}

Styling

The Connect component uses class names that you can override:

/* Override default styles */
.ovi-connect-form {
  /* Form container */
}

.ovi-connect-input {
  /* Username input */
}

.ovi-connect-button {
  /* Submit button */
}

.ovi-connect-status {
  /* Status message (username availability) */
}

Multi-Step Form Example

'use client';

import { useState } from 'react';
import { Connect } from '@oviato/connect/client';

export default function OnboardingPage() {
  const [step, setStep] = useState(1);

  return (
    <div className="onboarding">
      {step === 1 && (
        <div>
          <h2>Step 1: Welcome</h2>
          <button onClick={() => setStep(2)}>Next</button>
        </div>
      )}

      {step === 2 && (
        <div>
          <h2>Step 2: Connect Wallet</h2>
          <Connect
            callback={() => {
              setStep(3);
            }}
          />
        </div>
      )}

      {step === 3 && (
        <div>
          <h2>You're all set!</h2>
        </div>
      )}
    </div>
  );
}

ConnectButton

A flexible authentication button that triggers the Oviato passkey flow. Use this when you want to build your own UI but need a simple connect button.

Basic Usage

import { ConnectButton } from '@oviato/connect/client';

function MyComponent() {
  return (
    <ConnectButton
      text="Connect Wallet"
      onSuccess={(data) => {
        console.log('Connected:', data.address);
      }}
      onError={(error) => {
        console.error('Failed:', error);
      }}
    />
  );
}

Props

interface ConnectButtonProps {
  /** Text for default button (default: "Signup / Login with Passkey") */
  text?: string;

  /** Custom children to render instead of default button */
  children?: ReactNode;

  /** Callback fired on successful authentication */
  onSuccess?: (data: {
    address: string;
    publicKey: string;
    username: string;
  }) => void;

  /** Callback fired on authentication error */
  onError?: (error: Error) => void;

  /** Custom className for default button (ignored if children provided) */
  className?: string;

  /** Authentication method (default: 'iframe') */
  method?: 'iframe' | 'popup';
}

Custom Children

Use your own button component:

import { ConnectButton } from '@oviato/connect/client';

function MyComponent() {
  return (
    <ConnectButton onSuccess={(data) => console.log(data)}>
      <button className="my-custom-button">
        🔐 Connect with Passkey
      </button>
    </ConnectButton>
  );
}

With Callback Handling

import { ConnectButton } from '@oviato/connect/client';
import { useState } from 'react';

function MyComponent() {
  const [error, setError] = useState<string | null>(null);

  return (
    <div>
      <ConnectButton
        text="Connect Wallet"
        onSuccess={(data) => {
          console.log('Address:', data.address);
          console.log('Username:', data.username);
        }}
        onError={(error) => {
          setError(error.message);
        }}
      />
      {error && <p className="error">{error}</p>}
    </div>
  );
}

Choose between popup or iframe authentication:

// Iframe (default) - opens in modal overlay
<ConnectButton method="iframe" text="Connect" />

// Popup - opens in new browser window
<ConnectButton method="popup" text="Connect" />

When to use each:

Iframe (recommended): Better UX, stays in-page, works on mobile
Popup: Use when iframe is blocked or you need popup-specific behavior

Custom Auth Flow Example

'use client';

import { ConnectButton, useOviConnect } from '@oviato/connect/client';

export default function AuthPage() {
  const { session, disconnect } = useOviConnect();

  if (session) {
    return (
      <div className="wallet-info">
        <p>Connected: {session.address}</p>
        <button onClick={disconnect}>Disconnect</button>
      </div>
    );
  }

  return (
    <div className="auth-page">
      <h1>Welcome to My App</h1>
      <p>Connect your wallet to get started</p>

      <ConnectButton
        text="Connect Wallet"
        onSuccess={() => {
          console.log('Connected successfully!');
        }}
      />
    </div>
  );
}

Styling Components

All components support className and style props for customization:

// Using className
<ConnectButton
  className="my-button-class"
  text="Connect"
/>

// Using inline styles
<ConnectButton
  style={{ backgroundColor: 'blue', padding: '12px 24px' }}
  text="Connect"
/>

// Using custom children with full control
<ConnectButton>
  <button className="my-custom-button-class">
    <span>🔐</span>
    <span>Connect Wallet</span>
  </button>
</ConnectButton>

TypeScript Support

All components have full TypeScript support:

import type { ConnectButtonProps, ConnectProps } from '@oviato/connect/client';

const buttonProps: ConnectButtonProps = {
  text: 'Connect',
  onSuccess: (data) => {
    // data is fully typed
    console.log(data.address);
  },
};

const connectProps: ConnectProps = {
  callback: (data) => {
    // data is fully typed
    console.log(data.publicKey);
  },
};

Next Steps

Using Hooks - Learn about useOviConnect and useOviStore
Signing Messages - Sign messages with the wallet
Signing Transactions - Send transactions

Using Hooks

React hooks for Oviato Connect - useOviConnect and useOviStore

Signing Messages

Sign messages with passkeys using @oviato/connect

Components Reference

On this page