Mailmus
SDK Reference

React

The pre-built @mailmus/auth-react components — SignIn, SignUp, UserButton, MFA, and more.

Package: @mailmus/auth-react — ready-made components built on top of the @mailmus/auth browser SDK. It is the fastest way to add authentication to a React app without building your own forms.

npm install @mailmus/auth-react
import { MailmusAuthProvider, SignIn, SignedIn, SignedOut, UserButton } from "@mailmus/auth-react";
import "@mailmus/auth-react/styles.css";

function App() {
  return (
    <MailmusAuthProvider publishableKey="mailmus_publishable_key_live_...">
      <header>
        <UserButton />
      </header>

      <SignedOut>
        <SignIn redirectUri={window.location.origin + "/"} />
      </SignedOut>
      <SignedIn>
        <p>Signed in!</p>
      </SignedIn>
    </MailmusAuthProvider>
  );
}

publishableKey alone is enough in production — the project is decoded straight from the key, and serverURL/hostedPagesURL (optional props) point at production by default.

Hooks

const { isLoaded, isSignedIn, customer, actor } = useAuth();
// Reactive — it updates on every sign-in, sign-out and refresh.
// `actor` is the team member signed in as this user from your dashboard, or null.

const auth = useMailmusAuth();
// An escape hatch to the raw SDK client (auth.mfa, auth.oauth, auth.sessions,
// and so on) for anything with no dedicated component.

Components

ComponentWhat it does
<SignIn />Password, email code, OAuth, with the MFA challenge handled internally
<SignUp />Password, email code, OAuth
<UserButton />Avatar and dropdown (email address, sign out)
<SignedIn /> / <SignedOut />Conditional rendering based on the session
<MagicLinkVerify />Callback page for magic links
<VerifyEmail />Callback page for email verification
<MfaEnroll />Complete MFA enrollment — QR code, manual secret, backup codes
<MfaDisable />Turning MFA off
<ImpersonationBanner />Says a team member is signed in as this user. Shown automatically by the provider; place it yourself after impersonationBanner={false} (Sign in as a user)

The OAuth and MFA flows these components handle are covered in the OAuth and MFA guides — the behaviour is identical, only the presentation layer changes.

Language

The components speak the language you chose for your end-users in the dashboard — the same one the hosted sign-in pages and the authentication emails follow. A code that arrives by email in one language is typed into a form in that same language.

It is never guessed from the browser: a form that changed language with the visitor would contradict the email that brought them to it, and would leave you no way to know what your own users are reading.

// Follows the project: nothing to pass.
<MailmusAuthProvider publishableKey="mailmus_publishable_key_live_...">

// Your app already knows better — the visitor picked a language in your own UI.
<MailmusAuthProvider publishableKey="mailmus_publishable_key_live_..." locale="fr">

English and French today. useTextes() returns the same words if you build your own screens next to the pre-built ones and want them to match.

Styling

One stylesheet to import (@mailmus/auth-react/styles.css), classes prefixed mailmus-*, theming through CSS variables (--mailmus-primary, --mailmus-radius, --mailmus-border, and others) — no dependency on Tailwind.

Out of scope (on the roadmap)

<UserProfile>, and a Next.js middleware helper for protecting server routes. Use the raw SDK (useMailmusAuth()) or the browser SDK directly for those cases in the meantime.

Next

On this page