react-allauth

Typed React hooks for the django-allauth headless API — authentication, MFA, social login and more, wired up for you.

[!NOTE] This package is under active development. All hooks are implemented and tested, but the API may still change between 0.x releases. See Stability.

Documentation: guides and the full hook reference live at alexandre-petitjean.github.io/react-allauth.

Why this exists

django-allauth ships an excellent headless API, but its official front-end example is a demo SPA, not a reusable library. react-allauth turns that API into a small set of fully-typed React hooks: you get a provider, a flow-aware useAuth, and a contract that covers the entire headless surface (MFA, WebAuthn, social, sessions, email management) — without hand-rolling fetch calls and CSRF wiring in every project.

Install

npm install react-allauth

react and react-dom are peer dependencies (React 18 or 19):

npm install react react-dom

Quickstart

Wrap your app in <AllauthProvider> and use the hooks anywhere below it:

import { AllauthProvider, useAuth } from 'react-allauth'

function Account() {
  const { status, user, login, logout } = useAuth()

  if (status === 'loading') return <p>Loading…</p>
  if (status === 'authenticated') {
    return <button onClick={() => logout()}>Sign out {user?.display}</button>
  }
  return (
    <button onClick={() => login({ email: '[email protected]', password: 'secret' })}>
      Sign in
    </button>
  )
}

export function App() {
  return (
    <AllauthProvider baseUrl="https://api.example.com">
      <Account />
    </AllauthProvider>
  )
}

Hooks

| Hook | What it does | | --------------- | ------------------------------------------------------ | | useAuth | Session state, login / signup / logout / reauth, login by code | | useConfig | Fetch the one-shot allauth configuration | | usePassword | Change password and the reset-by-key flow | | useEmails | Manage email addresses and verification | | useMFA | TOTP, recovery codes and completing 2FA login | | useWebAuthn | Passkey signup, login, registration and management | | useSocialAuth | Provider redirect / token login and connected accounts | | useSessions | List and revoke active sessions |

Compatibility

• django-allauth: 65.18+ with allauth.headless enabled (HEADLESS_ONLY recommended).
• React: 18 or 19.
• Environment: browser only. No server-side rendering and no React Native — the default client relies on cookies. See the threat model for the trade-offs.

Stability

This package is in its 0.x phase: the API is still being shaped and breaking changes may land between 0.x releases (always noted in the CHANGELOG). Pin a version if you need stability. See VERSIONING.md for the full policy and the road to 1.0.0.

Security

react-allauth handles a security-critical part of your app. Please report vulnerabilities privately — see SECURITY.md — and read the threat model before relying on it.

Contributing

Contributions are welcome — see CONTRIBUTING.md. Common scripts:

| Script | Description | | -------------------- | ----------------------------------------- | | npm run dev | Run the playground app (Vite, with HMR) | | npm run build | Build the library (ESM + CJS + type defs) | | npm run test | Run the test suite with Vitest | | npm run test:watch | Run the test suite in watch mode | | npm run lint | Lint the source with ESLint | | npm run typecheck | Type-check the project with TypeScript |

Enable the git hooks once after cloning (lint, type-check, whitespace):

pre-commit install

A local allauth backend for development lives under playground/.

License

MIT © Alexandre Petitjean