Skip to main content

​
Password-Based Authentication

​
LoginForm

A form component for email and password authentication.

​
Props

This component has no props. It manages its own state internally.

​
State Management

The component uses useAuthActions from @convex-dev/auth/react to access the signIn method.

​
Internal State

​
email
string
User’s email address for authentication
​
password
string
User’s password for authentication
​
error
string | null
Error message to display if authentication fails
​
loading
boolean
Loading state during authentication process

​
Behavior

Submits authentication with flow: "signIn" to the Convex Auth password provider.

​
Example

import { LoginForm } from "@/components/login-form";

export default function LoginPage() {
  return <LoginForm />;
}

​
SignUpForm

A form component for user registration with email and password.

​
Props

This component has no props. It manages its own state internally.

​
State Management

The component uses useAuthActions from @convex-dev/auth/react to access the signIn method and useRouter from next/navigation for navigation.

​
Internal State

​
name
string
User’s display name
​
email
string
User’s email address
​
password
string
User’s password (minimum 8 characters)
​
confirmPassword
string
Password confirmation field
​
error
string | null
Error message to display if registration fails
​
loading
boolean
Loading state during registration process

​
Validation

  • Passwords must match
  • Password must be at least 8 characters
  • Email must be valid email format

​
Behavior

Submits registration with flow: "signUp" to the Convex Auth password provider. On success, redirects to /auth/sign-up-success.

​
Example

import { SignUpForm } from "@/components/sign-up-form";

export default function SignUpPage() {
  return <SignUpForm />;
}

​
ForgotPasswordForm

A form component for initiating password reset flow.

​
Props

This component has no props. It manages its own state internally.

​
State Management

The component uses useAuthActions from @convex-dev/auth/react to access the signIn method and useRouter from next/navigation for navigation.

​
Internal State

​
email
string
User’s email address to send reset code
​
error
string | null
Error message to display if request fails
​
success
boolean
Success state after code is sent
​
loading
boolean
Loading state during request process

​
Behavior

Submits password reset request with flow: "reset" to trigger the ResendOTPPasswordReset provider. Sends an 8-digit OTP code via email. On success, displays success message and button to proceed to update password page.

​
Example

import { ForgotPasswordForm } from "@/components/forgot-password-form";

export default function ForgotPasswordPage() {
  return <ForgotPasswordForm />;
}

​
UpdatePasswordForm

A form component for completing password reset with OTP code.

​
Props

This component has no props. It reads email from URL search parameters if available.

​
State Management

The component uses:
  • useAuthActions from @convex-dev/auth/react to access the signIn method
  • useRouter and useSearchParams from next/navigation for navigation and URL parameters

​
Internal State

​
email
string
User’s email address (can be pre-filled from URL parameter)
​
code
string
8-digit verification code received via email
​
password
string
New password (minimum 8 characters)
​
confirmPassword
string
Password confirmation field
​
error
string | null
Error message to display if update fails
​
loading
boolean
Loading state during update process

​
Validation

  • Email is required
  • Code must be provided (8 digits)
  • Passwords must match
  • Password must be at least 8 characters

​
Behavior

Submits password update with flow: "reset-verification" including the code, email, and new password. On success, redirects to /auth/login?message=password-updated.

​
Example

import { UpdatePasswordForm } from "@/components/update-password-form";

export default function UpdatePasswordPage() {
  return <UpdatePasswordForm />;
}

​
LogoutButton

A button component for signing out users.

​
Props

​
showIcon
boolean
default:"true"
Whether to display the logout icon
​
children
React.ReactNode
default:"Sign out"
Button text content
​
...props
React.ComponentProps<typeof Button>
All other Button component props are supported

​
State Management

The component uses useAuthActions from @convex-dev/auth/react to access the signOut method.

​
Example

import { LogoutButton } from "@/components/logout-button";

export default function Header() {
  return (
    <div>
      <LogoutButton />
      {/* Custom variant */}
      <LogoutButton variant="destructive" showIcon={false}>
        Log out
      </LogoutButton>
    </div>
  );
}

​
Social Authentication

​
SocialLoginForm

A form component for OAuth authentication with social providers.

​
Props

​
providers
Provider[]
default:"[\"github\", \"google\"]"
Array of OAuth providers to display. Supported values: "github", "google"

​
Types

type Provider = "github" | "google";

interface SocialLoginFormProps {
  providers?: Provider[];
}

​
State Management

The component uses useAuthActions from @convex-dev/auth/react to access the signIn method.

​
Internal State

​
error
string | null
Error message to display if authentication fails
​
loadingProvider
Provider | null
Tracks which provider is currently being used for authentication

​
Behavior

Initiates OAuth flow by calling signIn(provider) where provider is the selected OAuth provider (e.g., “github” or “google”).

​
Example

import { SocialLoginForm } from "@/components/login-form";

export default function LoginPage() {
  return (
    <div>
      {/* Default providers */}
      <SocialLoginForm />
      
      {/* GitHub only */}
      <SocialLoginForm providers={["github"]} />
      
      {/* Google only */}
      <SocialLoginForm providers={["google"]} />
    </div>
  );
}

Build docs developers (and LLMs) love

Get started for freeTalk to us