remix/form

[okalil]

This proposal describes a first-party unified API for progressively enhanced FormData-based actions.

The problem

A great form user experience requires more than returning an HTTP response.

Users already expect live feedback as they interact with a form:

• They expect a field error to disappear as soon as they correct it
• They expect a spinner on the submit button they just clicked
• They expect focus to move to the first invalid field after a validation error
• They expect a toggle to update instantly when they click it (optimistic UI)

In addition, form libraries in other frameworks have set a floor for what developers expect:

• Typed errors
• Typed field names
• Validation shared between client and server
• One API for navigational and non-navigational forms
• One API for declarative and imperative submissions

Proposal

Ship a first-party remix/form package built on three primitives:

• Form handles state, validation, and submit.
• Field handles per-field value, error, and change events.
• form mixin wires a <form> to a Form instance.

Use cases

Navigational forms

• Form is the core API for state management, validation, and submit handling.
  • state provides live errors and pending status for instant feedback.
• Field is the API for field-level management.
• form mixin handles the submit event: it runs the client-side validation before submitting and resets the form after a successful result.
• toDraft and toErrors turn FormData and schema issues into draft and error props so an action can re-render the form with values and errors intact.

const loginForm = new Form({
  method: 'post',
  schema: loginSchema,
  draft: () => handle.props.draft,
  errors: () => handle.props.errors,
});

addEventListeners(loginForm, handle.signal, {
  statechange: () => handle.update(),
});

return () => {
  const { errors, pending } = loginForm.state;
  return (
    <form mix={form(loginForm)}>
      <TextField field={loginForm.field('email')} label="Email" type="email" />
      <TextField
        field={loginForm.field('password')}
        label="Password"
        type="password"
      />
      {errors.root && <ErrorMessage error={errors.root} />}
      <Button type="submit" pending={pending}>
        Log in
      </Button>
    </form>
  );
};

const validation = parseSafe(loginSchema, context.formData);
if (!validation.success) {
  return context.render(
    <LoginForm
      draft={toDraft(context.formData, { omit: ['password'] })}
      errors={toErrors(validation.issues)}
    />,
    { status: 422 },
  );
}

Non-navigational forms

• By default, the form mixin lets the browser submit the form (and remix/ui handles the navigation).
• navigate: false prevents that navigation and submits with fetch to the form's action instead.
• A submitcomplete listener can then reload the frame to revalidate displayed data.
• e.waitUntil keeps pending true until the reload finishes.

const editCommentForm = new Form({
  method: 'put',
  action: routes.comments.edit.href({ id: comment.id }),
  schema: editCommentSchema,
  draft: () => [['content', comment.content]],
});

addEventListeners(editCommentForm, handle.signal, {
  statechange: () => handle.update(),
  submitcomplete: (e) => e.waitUntil(handle.frame.reload()),
});

return () => (
  <form mix={form(editCommentForm, { navigate: false })}>
    <TextAreaField field={editCommentForm.field('content')} label="Write" />
    <Button type="submit" pending={editCommentForm.state.pending}>
      Update comment
    </Button>
  </form>
);

Imperative non-navigational forms

• Form.submit() can run without a <form> submit event.

const form = new Form({
  method: 'delete',
  action: routes.comments.destroy.href({ id: handle.props.id }),
});

addEventListeners(form, handle.signal, {
  statechange: () => handle.update(),
  submitcomplete: (e) => e.waitUntil(handle.frames.top.reload()),
});

return () => (
  <Button
    type="button"
    pending={form.state.pending}
    mix={on('click', (_, signal) => void form.submit({ signal }))}
  >
    Delete Comment
  </Button>
);

Reacting to field changes

• Field is an event target. Listen for change to react when the field value updates.

const profileForm = new Form({
  method: 'post',
  schema: updateProfileSchema,
  draft: () => handle.props.draft,
  errors: () => handle.props.errors,
});
const avatarField = profileForm.field('avatar');

let previewUrl: string | null = null;

addEventListeners(profileForm, handle.signal, {
  statechange: () => handle.update(),
});
addEventListeners(avatarField, handle.signal, {
  change() {
    const file = avatarField.value;
    previewUrl = file?.size ? URL.createObjectURL(file) : null;
    handle.update();
  },
});

return () => (
  <form encType="multipart/form-data" mix={form(profileForm)}>
    <Avatar src={previewUrl ?? handle.props.user.avatar} />
    <FileField field={avatarField} accept="image/*" />
    {/* … */}
  </form>
);

Optimistic UI

• Form.state.submission holds the in-flight submission data and is cleared when the submission ends.
• e.waitUntil keeps the optimistic value until the frame reload completes.

const form = new Form({
  method: 'post',
  action: routes.discussions.vote.href({ id: handle.props.id }),
  schema: voteDiscussionSchema,
});

addEventListeners(form, handle.signal, {
  statechange: () => handle.update(),
  submitcomplete: (e) => e.waitUntil(handle.frame.reload()),
});

return () => {
  const optimisticVoted = form.state.submission?.data.voted;
  const voted = optimisticVoted ?? handle.props.voted;

  return (
    <button
      type="button"
      mix={on('click', (_, signal) => {
        form.formData.set('voted', String(!voted));
        form.submit({ signal });
      })}
    >
      {voted ? 'Remove upvote' : 'Upvote'}
    </button>
  );
};

Custom handlers

• Form.submit (and the form mixin) accept a handler that replaces the default fetch.
• Useful when the client talks to an API directly instead of a Remix action.

<form
  mix={form(loginForm, {
    async handler(data, signal) {
      await api.post('/v1/login', data, { signal });
    },
  })}
>
  {/* … */}
</form>

Possible objections

Why not native HTML constraints?

Native constraints (required, minLength, type, …) work without JavaScript. They are a good first line of defense, not the validation API.

• They do not share a schema with the server
• They do not produce typed, renderable field errors
• They do not cover cross-field rules, coerced values, or file validation
• Browser validation UI is inconsistent and hard to style

This package sets noValidate and runs the same schema on the client that the action runs on the server. Without JavaScript, the browser still POSTs FormData and the server still restores the form via toDraft and toErrors. Native attributes stay available for accessibility (type, aria-required). Deriving constraints from the schema is complementary and can be added later. The schema is the source of truth.

Why FormData?

A no-JS form submit is FormData (application/x-www-form-urlencoded or multipart/form-data). Remix actions already receive that. Files require it.

A JSON (or typed-object) request body would split the API: one path with JavaScript, another without. FormData is the request. The schema parses it. The client-side API does not keep a separate values object.

Resources

• These APIs are implemented in packages/form.