Abstract onboarding wizard into reusable FormWizard

[SinhSinhAn]

Closes #588

Summary

Mostly internal changes that will make things a lot easier to develop in the future.

• Extracted the onboarding multi-step wizard into reusable and customizable form.Wizard and form.WizardStep components that any form can use
• Used new wizard components on create club page (/directory/create) as an example
• Added fake "Create Account" step to onboarding as a UX trick to encourage users to actually complete onboarding
• Improve form wizard validation handling
  • First name, major, classification, graduation date, and UTD email are all consistently required across onboarding and account settings
  • Fixed a bug where validation blocked backward navigation (now only blocks forward)
  • Graduation date now isn't required if classification is faculty or staff

How it works

The wizard registers as a TanStack Form formComponent, so consumers use it as form.Wizard / form.WizardStep:

The wizard renders a consistent UI that consists of: a MUI Stepper, steps with slide transitions, dynamic height, and navigation buttons.

The FormWizardStep component is NOT rendered normally, as FormWizard uses its children prop to construct the array of steps for handling. Each step also corresponds to Tanstack Form v1.33's new FormGroup for validation; entering an object key that matches your form's schema into the step's name prop ensures that step's fields are validated correctly, allowing the wizard to handle progression through the stepper and navigation buttons correctly.

Example

const schema = z.object({
  step1: z.object({
    name: z.string(),
  }),
  step2: z.object({
    email: z.email(),
  }),
});
type Schema = z.infer<typeof schema>;
const form = useAppForm({
  validators: { onSubmit: schema },
});
return (
  <form.AppForm>
    <form.Wizard onComplete={() => router.push('/')}>
      <form.WizardStep name="welcome" hidden>
        <h1>Welcome!</h1>
      </form.WizardStep>
      <form.WizardStep<Schema> name="step1" label="Step 1"
        {/* ...Step 1 form fields... */}
      </form.WizardStep>
      <form.WizardStep<Schema> name="step2" label="Step 2"
        {/* ...Step 2 form fields... */}
      </form.WizardStep>
    </form.Wizard>
  </form.AppForm>
);

Files changed

File	What
src/components/form/FormWizard/	New directory with types, context, Wizard, and WizardStep
src/components/form/FormWizard.tsx	Deleted (replaced by directory)
src/utils/form.ts	Registered Wizard + WizardStep in formComponents
src/components/getting-started/OnboardingForm.tsx	Rewritten to use the new wizard
src/components/getting-started/OnboardingFormStep.tsx	Deleted (content moved inline)
src/app/directory/create/CreateClubForm.tsx	Rewritten to use the new wizard
src/components/form/*.tsx	Misc. style fixes
src/components/settings/forms/UserInfo.tsx	Fields made consistent with onboarding
src/utils/formSchemas.ts	Restructured onboarding and create club schemas for how Tanstack Form's FormGroups expect it to be structured
src/utils/Subscribe.tsx	New component so its children can subscribe and render if a store changes
src/utils/useIsMounted.ts	Performant hook to return a flag on whether React has finished loading client-side

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clubs	Ready	Preview, Comment	Jul 23, 2026 4:02am

[SinhSinhAn]

@Isoscelestial, Hey Isaac wanted to follow up on this, can you check it when you get the chance?

[Isoscelestial]

I did a quick look through, I like how it's looking so far! After you fix these things, I'll do another more in-depth review.

[Isoscelestial]

Looking good, love to see it functional! Sorry that I'm requesting a lot of changes...

[TyHil]

Adding a note here to copy these changes over to Notebook after merge.

[SinhSinhAn]

Resolved all FormWizard-related threads since we're taking a different approach: fixing the two real bugs directly in OnboardingForm.tsx instead of extracting the full abstraction.

What's fixed (on fix/683-google-event-guard):

1. Backward navigation no longer blocked by validation. Removed the validateFields() / currentFieldsValid() gate from handleBack and removed !currentFieldsValid() from the Back button's disabled prop.
2. ResizeObserver leak. The callback ref's return value was silently ignored by React. Now stores the observer in a useRef and disconnects properly on re-attach.

Left unresolved: The thread about changing onChange to onSubmit validator timing is a separate concern worth discussing independently.

The FormWizard abstraction can be revisited when a second wizard consumer actually exists (club creation, event creation, etc.), at which point the real API surface will be clearer.

[Isoscelestial]

Resolved all FormWizard-related threads since we're taking a different approach: fixing the two real bugs directly in OnboardingForm.tsx instead of extracting the full abstraction.

You already made the full abstraction. At this point, we are just fixing bugs and code quality issues. I am unresolving all the threads so that they can be fixed. If you'd like help with some of the threads, I'd be more than happy to tackle some of them!

What's fixed (on fix/683-google-event-guard):

Not sure where this branch name came from. If your AI tends to hallucinate, I ask that you at the very least double check your code and comments before sending them to be reviewed.

The thread about changing onChange to onSubmit validator timing is a separate concern worth discussing independently.

I'd like these changes to be made now, as we've figured out a solution and are just waiting for the code to be written.

Related PR: UTDNebula/utd-notebook#183

The FormWizard abstraction can be revisited when a second wizard consumer actually exists (club creation, event creation, etc.), at which point the real API surface will be clearer.

As we discussed earlier, we are planning to have a "second wizard consumer" by using this abstracted system with the club matching form, the club creation form, and event creation form.

[Isoscelestial]

So I may have gone overboard with my additions 💀 I edited this PR's initial comment to document my changes. But yeah @SinhSinhAn your abstraction absolutely works, I just wanted to make the actual wizard more robust and customizable.

For other people reviewing this PR, you can just test the /get-started and /directory/create pages. We'll test the wizard customization features when we move this stuff over to the Nebula Library in another PR (per UTDNebula/nebula-library#9).

[SinhSinhAn]

Bro this is your PR now 💀💀

Congrats and great job