SignInFlow

Code

import { AuthLayout, SignInFlow } from "@fadymondy/nasaq/web";export function SignInPage() {  return (    <AuthLayout      title="Sign in"      prompt={<>Don't have an account? <a href="/sign-up">Create one</a></>}    >      <SignInFlow        onPassword={async ({ email, password, remember }) => {          const res = await api.signIn(email, password, remember);          if (!res.ok) return { error: "Wrong email or password." };        }}        forgotPassword={<a href="/forgot-password">Forgot password?</a>}      />    </AuthLayout>  );}

Auth · beta

Live examples and controls: SignInFlow in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/sign-in-flow.json

The sign-in that starts with one question: which email? The first screen shows only an email field, the OAuth providers and (when supported) a passkey button. Your backend looks at the address and answers with the next step:

• password: the account has a password.
• code: a one-time code was emailed.
• sso: the domain belongs to an organisation with single sign-on, so no password is asked here at all.
• register: no account uses this address; offer sign-up.
• link-sent: a sign-in link was emailed.
• blocked: this address may not sign in here (suspended, another tenant, no allowed method).

After a password, onPassword can answer { twoFactor: true } and the flow asks for a second factor with TwoFactorChallenge. With onForgotPassword, "Forgot password?" opens ForgotPasswordForm in place with the email filled in.

Every later step shows the chosen email with a Change button, so people can always go back.

When to useCopy Anchor Link

• The default sign-in for any product, and the only sane one when some customers use SSO.
• When you want to add passkeys, codes or SSO later without redesigning the first screen.

When not to useCopy Anchor Link

• A single-method product that will only ever have email + password: LoginForm is shorter.
• Sign-up: use RegisterForm (the register step hands off to it with onRegister).

ImportCopy Anchor Link

import { SignInFlow } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

The smallest sign-in: email first, then the password. Without onIdentify every address goes to the password step.

import { AuthLayout, SignInFlow } from "@fadymondy/nasaq/web";

export function SignInPage() {
  return (
    <AuthLayout
      title="Sign in"
      prompt={<>Don't have an account? <a href="/sign-up">Create one</a></>}
    >
      <SignInFlow
        onPassword={async ({ email, password, remember }) => {
          const res = await api.signIn(email, password, remember);
          if (!res.ok) return { error: "Wrong email or password." };
        }}
        forgotPassword={<a href="/forgot-password">Forgot password?</a>}
      />
    </AuthLayout>
  );
}

Email only (passwordless). Leave out onIdentify and onPassword: the flow emails a code and asks for it.

<SignInFlow
  onRequestCode={async (email) => { await api.sendCode(email); }}
  onCode={async ({ email, code }) => {
    const res = await api.verifyCode(email, code);
    if (!res.ok) return { error: "That code is not right." };
  }}
/>

Magic link only. Leave out onIdentify, onPassword and onRequestCode: every address gets a sign-in link.

<SignInFlow onMagicLink={async (email) => { await api.sendLink(email); }} />

Full flow. Let the backend pick the step for each address:

import { AuthLayout, SignInFlow, type SignInStep } from "@fadymondy/nasaq/web";
import { useState } from "react";

export function SignInPage() {
  const [step, setStep] = useState<SignInStep>("email");
  return (
    <AuthLayout title={step === "email" ? "Sign in" : "Welcome back"}>
      <SignInFlow
        onStepChange={setStep}
        onIdentify={async (email) => (await api.lookup(email)).next} // { step: "password" | "code" | "sso" | "register" }
        onPassword={async ({ email, password, remember }) => {
          const res = await api.signIn(email, password, remember);
          if (!res.ok) return { error: "Wrong email or password." };
        }}
        onTwoFactor={async ({ email, code, method, trustDevice }) => api.verify2fa(email, code, method, trustDevice)}
        onMagicLink={async (email) => { await api.sendLink(email); }}
        onForgotPassword={async (email) => { await api.sendReset(email); }}
        onSso={(email) => { window.location.href = `/sso/start?email=${encodeURIComponent(email)}`; }}
        onRegister={(email) => router.push(`/sign-up?email=${encodeURIComponent(email)}`)}
        oauthProviders={["google", "microsoft"]}
        onOAuth={(id) => { window.location.href = `/oauth/${id}`; }}
      />
    </AuthLayout>
  );
}

AnatomyCopy Anchor Link

SignInFlow                        data-slot="sign-in-flow", data-step="email" | "password" | "code" | "sso" | "register"
                                  | "link-sent" | "blocked" | "two-factor" | "forgot"
└─ step                           data-slot="sign-in-flow-step" (remounts on every step, so it re-enters)
   ├─ email step
   │  ├─ form                     data-slot="sign-in-flow-email": email field + Continue
   │  ├─ OAuthDivider + OAuthButtons
   │  └─ passkey button           data-slot="sign-in-flow-passkey"
   └─ later steps
      ├─ identity chip            data-slot="sign-in-flow-identity": the email + Change
      └─ password form | VerifyOtpForm | TwoFactorChallenge | SSO notice | register notice
         | link sent (data-slot="sign-in-flow-link-sent", resend "sign-in-flow-resend")
         | blocked notice (data-slot="sign-in-flow-blocked")
   forgot step                    data-slot="sign-in-flow-forgot": ForgotPasswordForm + Back to sign in (no identity chip)

APICopy Anchor Link

SignInFlow: every div prop, plus:

SignInNext is { step: "password"; alternatives? } | { step: "code"; length? } | { step: "sso"; connection? } | { step: "register" } | { step: "link-sent" } | { step: "blocked"; message? }. alternatives (SignInAlternative[]: "code", "magic-link") limits the other ways in on the password step for that address; [] hides them. SignInStep is "email", one of those steps, "two-factor" or "forgot".

ExamplesCopy Anchor Link

Route by domain on the server (the lab story does the same with a fake backend):

async function lookup(email: string): Promise<SignInNext> {
  const org = await orgs.byDomain(email.split("@")[1]);
  if (org?.sso) return { step: "sso", connection: org.ssoName };
  const user = await users.byEmail(email);
  if (!user) return { step: "register" };
  if (user.suspended) return { step: "blocked" };
  return user.hasPassword ? { step: "password", alternatives: user.allowLinks ? undefined : [] } : { step: "code" };
}

AccessibilityCopy Anchor Link

• Each step is a real <form> with labelled fields; errors use the shared error summary and move focus to it.
• The email field is focused on load; the password and code steps focus their field when they open.
• The password step keeps a hidden username field with the email, so password managers save the right pair.
• The email field uses autocomplete="username webauthn" when passkey autofill is on.
• The password step warns "Caps Lock is on." in a role="status" region under the field, so screen readers hear it too. It clears when Caps Lock goes off or the field loses focus.
• The "Last used" badge is text inside the button, so it is part of the button's accessible name.
• The link-sent step is a role="status" region and its heading takes focus; the resend button counts down and a polite status says when a new link went out.

Security notesCopy Anchor Link

• Asking for the email first means your backend decides what to reveal. If you do not want to leak whether an account exists, never return register: return password or code for every address and fail at the next step.
• Return blocked only when you are happy to say the address exists; otherwise fail at the next step.
• SSO domains never see a password field, so users cannot type their IdP password into your app.
• Put the flow in AuthLayout: its origin line confirms a secure connection and names the host under the card, and it turns into a warning on an insecure page.
• lastUsed helps people pick the same method again instead of creating a second account. Keep the cookie to the method id only, never the email.

MotionCopy Anchor Link

The steps enter with the AuthLayout stagger. On the first render they join the card's entrance; after a step change (data-moved) only the new step's rows rise 6px, 50ms apart, with no delay. prefers-reduced-motion turns it off.

RTL & i18nCopy Anchor Link

• English and Arabic strings are built in and follow the locale provider.
• The email is always shown LTR (<bdi dir="ltr">) and the field is ltr, in both directions.
• The Change arrow points back in the reading direction (it flips in RTL).

Styling & tokensCopy Anchor Link

• Only --nq-* tokens. The notices use the card radius and border-border.
• Target steps with [data-slot="sign-in-flow"][data-step="…"].

Do / Don'tCopy Anchor Link

• Do keep the first screen to the email, the providers and a passkey.
• Do name the SSO connection (connection: "Acme Okta") so people recognise it.
• Don't ask for the password on the first screen: that is LoginForm.
• Don't put the flow in a dialog; it owns focus between steps.

RelatedCopy Anchor Link

• auth-layout
• login-form
• oauth-buttons
• verify-otp-form
• two-factor-challenge
• forgot-password-form
• reset-password-form
• password-input

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-auth-sign-in-flow--docs