Implement experimental_useFormStatus

[acdlite]

This hook reads the status of its ancestor form component, if it exists.

const {pending, data, action, method} = useFormStatus();

It can be used to implement a loading indicator, for example. You can think of it as a shortcut for implementing a loading state with the useTransition hook.

For now, it's only available in the experimental channel. We'll share docs once its closer to being stable. There are additional APIs that will ship alongside it.

Internally it's implemented using startTransition + a context object. That's a good way to think about its behavior, but the actual implementation details may change in the future.

Because form elements cannot be nested, the implementation in the reconciler does not bother to keep track of multiple nested "transition providers". So although it's implemented using generic Fiber config methods, it does currently make some assumptions based on React DOM's requirements.

[react-sizebot]

Comparing: 6eadbe0...1279935

Critical size changes

Includes critical production bundles, as well as any change greater than 2%:

Name	+/-	Base	Current	+/- gzip	Base gzip	Current gzip
oss-stable/react-dom/cjs/react-dom.production.min.js	=	164.02 kB	164.02 kB	=	51.71 kB	51.71 kB
oss-experimental/react-dom/cjs/react-dom.production.min.js	+0.35%	169.73 kB	170.32 kB	+0.40%	53.41 kB	53.62 kB
facebook-www/ReactDOM-prod.classic.js	=	566.81 kB	566.81 kB	=	100.13 kB	100.13 kB
facebook-www/ReactDOM-prod.modern.js	=	550.54 kB	550.55 kB	+0.01%	97.32 kB	97.33 kB

Significant size changes

Includes any change greater than 0.2%:

Expand to show

Name	+/-	Base	Current	+/- gzip	Base gzip	Current gzip
oss-experimental/react-art/cjs/react-art.development.js	+0.57%	808.77 kB	813.37 kB	+0.68%	176.04 kB	177.25 kB
oss-experimental/react-art/cjs/react-art.production.min.js	+0.53%	96.68 kB	97.20 kB	+0.57%	29.71 kB	29.88 kB
oss-experimental/react-art/umd/react-art.development.js	+0.52%	923.99 kB	928.79 kB	+0.61%	195.07 kB	196.26 kB
oss-experimental/react-reconciler/cjs/react-reconciler.development.js	+0.49%	909.66 kB	914.08 kB	+0.60%	194.51 kB	195.67 kB
oss-experimental/react-reconciler/cjs/react-reconciler.production.min.js	+0.45%	113.90 kB	114.42 kB	+0.50%	34.85 kB	35.02 kB
oss-experimental/react-dom/cjs/react-dom.development.js	+0.43%	1,291.02 kB	1,296.55 kB	+0.56%	285.17 kB	286.76 kB
oss-experimental/react-dom/umd/react-dom.development.js	+0.43%	1,353.57 kB	1,359.35 kB	+0.55%	288.03 kB	289.62 kB
oss-experimental/react-dom/cjs/react-dom-unstable_testing.development.js	+0.42%	1,309.07 kB	1,314.61 kB	+0.54%	289.51 kB	291.07 kB
oss-experimental/react-reconciler/cjs/react-reconciler.profiling.min.js	+0.42%	122.91 kB	123.43 kB	+0.42%	37.05 kB	37.20 kB
oss-experimental/react-art/umd/react-art.production.min.js	+0.38%	133.94 kB	134.46 kB	+0.25%	41.95 kB	42.06 kB
oss-experimental/react-dom/cjs/react-dom.production.min.js	+0.35%	169.73 kB	170.32 kB	+0.40%	53.41 kB	53.62 kB
oss-experimental/react-dom/umd/react-dom.production.min.js	+0.35%	169.57 kB	170.16 kB	+0.31%	53.76 kB	53.93 kB
oss-experimental/react-dom/cjs/react-dom-unstable_testing.production.min.js	+0.34%	175.94 kB	176.53 kB	+0.42%	55.73 kB	55.96 kB
oss-experimental/react-server/cjs/react-server.production.min.js	+0.34%	25.01 kB	25.10 kB	+0.28%	8.55 kB	8.57 kB
oss-experimental/react-dom/umd/react-dom.profiling.min.js	+0.33%	178.55 kB	179.14 kB	+0.35%	56.09 kB	56.28 kB
oss-experimental/react-dom/cjs/react-dom.profiling.min.js	+0.33%	179.36 kB	179.95 kB	+0.31%	55.87 kB	56.04 kB

Generated by 🚫 dangerJS against 1279935

[acdlite]

@sebmarkbage This is ready for review now except for the Flow error (which I don't yet understand)

[debel27]

Is this a general-purpose hook?

I often have the situation where the submit <button> is located outside the <form> element.

<form id="form-id">
  {/* ... */}
</form>

<button type="submit" form="form-id">
  Submit
</button>

Ideally, I'd like to display a loading indicator inside the button when the form is submitting. It does not seem feasible with the current version of useFormStatus. Is it out of scope?

[acdlite]

#26722 (comment)

Ideally, I'd like to display a loading indicator inside the button when the form is submitting. It does not seem feasible with the current version of useFormStatus. Is it out of scope?

That's a feature we've discussed adding (like by passing the id of the form as an argument to the hook) but it won't be in the initial version. But in the meantime there will be lower level APIs that you can use to implement a loading state yourself. (The same ones you'd use for anything more advanced that what useFormStatus provides out of the box.)

[nihgwu]

But in the meantime there will be lower level APIs that you can use to implement a loading state yourself. (The same ones you'd use for anything more advanced that what useFormStatus provides out of the box.)

@acdlite can you elaborate, is there quick ways without top level context?

That's a feature we've discussed adding

When can we expect it be available, IMO the current implementation is incomplete, as in practice submit button outside of form while connected with id is the only way in some cases