prototyping form actions

devongovett · devongovett · commit f08bc6344e2a · 2026-04-15T11:50:46.000-07:00
diff --git a/packages/react-aria-components/exports/Alert.ts b/packages/react-aria-components/exports/Alert.ts
@@ -0,0 +1,18 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// Mark as a client only package. This will cause a build time error if you try
+// to import it from a React Server Component in a framework like Next.js.
+import 'client-only';
+
+export {Alert, AlertContext} from '../src/Alert';
+export type {AlertProps, AlertRenderProps} from '../src/Alert';
diff --git a/packages/react-aria-components/exports/index.ts b/packages/react-aria-components/exports/index.ts
@@ -14,6 +14,7 @@
 // to import it from a React Server Component in a framework like Next.js.
 import 'client-only';
 
+export {Alert, AlertContext} from '../src/Alert';
 export {Autocomplete, AutocompleteContext, AutocompleteStateContext, SelectableCollectionContext, FieldInputContext} from '../src/Autocomplete';
 export {Breadcrumbs, BreadcrumbsContext, Breadcrumb} from '../src/Breadcrumbs';
 export {Button, ButtonContext} from '../src/Button';
@@ -101,6 +102,7 @@ export type {CollectionProps} from 'react-aria/Collection';
 export type {Placement} from 'react-aria/useOverlayPosition';
 export type {VisuallyHiddenProps} from 'react-aria/VisuallyHidden';
 
+export type {AlertProps, AlertRenderProps} from '../src/Alert';
 export type {AutocompleteProps, SelectableCollectionContextValue} from '../src/Autocomplete';
 export type {BreadcrumbsProps, BreadcrumbProps, BreadcrumbRenderProps} from '../src/Breadcrumbs';
 export type {ButtonProps, ButtonRenderProps} from '../src/Button';
diff --git a/packages/react-aria-components/src/Alert.tsx b/packages/react-aria-components/src/Alert.tsx
@@ -0,0 +1,73 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {ContextValue, RenderProps, useContextProps, useRenderProps} from './utils';
+import {DOMProps} from '@react-types/shared';
+import {filterDOMProps} from 'react-aria/filterDOMProps';
+import React, {createContext, ForwardedRef, forwardRef, useEffect, useRef} from 'react';
+import {useFocusRing} from 'react-aria/useFocusRing';
+import {useObjectRef} from 'react-aria/useObjectRef';
+
+export interface AlertProps extends RenderProps<AlertRenderProps>, DOMProps {
+  /**
+   * Whether to automatically focus the alert when it first renders.
+   */
+  autoFocus?: boolean
+}
+
+export interface AlertRenderProps {
+  /**
+   * Whether the button is focused, either via a mouse or keyboard.
+   * @selector [data-focused]
+   */
+  isFocused: boolean,
+  /**
+   * Whether the button is keyboard focused.
+   * @selector [data-focus-visible]
+   */
+  isFocusVisible: boolean
+}
+
+export const AlertContext = createContext<ContextValue<AlertProps, HTMLDivElement>>(null);
+
+export const Alert = forwardRef(function Alert(props: AlertProps, ref: ForwardedRef<HTMLDivElement>) {
+  [props, ref] = useContextProps(props, ref, AlertContext);
+  let domProps = filterDOMProps(props, {global: true})!;
+  let {isFocused, isFocusVisible, focusProps} = useFocusRing({autoFocus: props.autoFocus});
+  let renderProps = useRenderProps({
+    ...props,
+    defaultClassName: 'react-aria-Alert',
+    values: {
+      isFocused,
+      isFocusVisible
+    }
+  });
+
+  let autoFocusRef = useRef(props.autoFocus);
+  let domRef = useObjectRef(ref);
+  useEffect(() => {
+    if (autoFocusRef.current && domRef.current) {
+      domRef.current.focus();
+    }
+    autoFocusRef.current = false;
+  }, [domRef]);
+
+  return (
+    <div
+      {...domProps}
+      {...focusProps}
+      {...renderProps}
+      ref={domRef}
+      role="alert"
+      tabIndex={props.autoFocus ? -1 : undefined} />
+  );
+});
diff --git a/packages/react-aria-components/src/Button.tsx b/packages/react-aria-components/src/Button.tsx
@@ -22,11 +22,12 @@ import {
 } from './utils';
 import {createHideableComponent} from 'react-aria/private/collections/Hidden';
 import {filterDOMProps} from 'react-aria/filterDOMProps';
+import {FormPendingContext} from './Form';
 import {GlobalDOMAttributes} from '@react-types/shared';
 import {HoverEvents} from '@react-types/shared';
 import {mergeProps} from 'react-aria/mergeProps';
 import {ProgressBarContext} from './ProgressBar';
-import React, {createContext, ForwardedRef} from 'react';
+import React, {createContext, ForwardedRef, useContext} from 'react';
 import {useFocusRing} from 'react-aria/useFocusRing';
 import {useHover} from 'react-aria/useHover';
 
@@ -88,7 +89,14 @@ export const ButtonContext = createContext<ContextValue<ButtonContextValue, HTML
 export const Button = /*#__PURE__*/ createHideableComponent(function Button(props: ButtonProps, ref: ForwardedRef<HTMLButtonElement>) {
   [props, ref] = useContextProps(props, ref, ButtonContext);
   let ctx = props as ButtonContextValue;
-  let {buttonProps, progressBarProps, isPressed, isPending, actionError} = useButton(props, ref);
+
+  // Ideally we would use React's `useFormStatus` for this but it is buggy.
+  // https://github.com/facebook/react/issues/30368
+  let isFormPending = useContext(FormPendingContext);
+  let {buttonProps, progressBarProps, isPressed, isPending, actionError} = useButton({
+    ...props,
+    isPending: props.isPending || (props.type === 'submit' && isFormPending)
+  }, ref);
   let {focusProps, isFocused, isFocusVisible} = useFocusRing(props);
   let {hoverProps, isHovered} = useHover({
     ...props,
diff --git a/packages/react-aria-components/src/Form.tsx b/packages/react-aria-components/src/Form.tsx
@@ -10,12 +10,14 @@
  * governing permissions and limitations under the License.
  */
 
-import {ContextValue, dom, DOMProps, DOMRenderProps, useContextProps} from './utils';
+import {AlertContext} from './Alert';
+import {ContextValue, dom, Provider, RenderProps, useContextProps, useRenderProps} from './utils';
 import {FormValidationContext} from 'react-stately/private/form/useFormValidationState';
 import {GlobalDOMAttributes, FormProps as SharedFormProps} from '@react-types/shared';
-import React, {createContext, ForwardedRef, forwardRef} from 'react';
+import React, {createContext, ForwardedRef, forwardRef, useMemo} from 'react';
+import {useAction} from 'react-stately/private/utils/useAction';
 
-export interface FormProps extends SharedFormProps, DOMProps, DOMRenderProps<'form', undefined>, GlobalDOMAttributes<HTMLFormElement> {
+export interface FormProps extends SharedFormProps, RenderProps<FormRenderProps, 'form'>, GlobalDOMAttributes<HTMLFormElement> {
   /**
    * The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element.
    * @default 'react-aria-Form'
@@ -27,25 +29,109 @@ export interface FormProps extends SharedFormProps, DOMProps, DOMRenderProps<'fo
    * or invalid via ARIA.
    * @default 'native'
    */
-  validationBehavior?: 'aria' | 'native'
+  validationBehavior?: 'aria' | 'native',
+  /**
+   * Async action that is called when the value changes.
+   * This differs from the React's `action` prop in a few ways:
+   * 
+   * * Errors thrown during the action are caught and passed to the `actionError` render prop.
+   * * The pending state is automatically passed to the form's submit button.
+   * * The form is not automatically reset after the action completes.
+   */
+  submitAction?: (data: FormData) => void | Promise<void>
+}
+
+export interface FormRenderProps {
+  /**
+   * Whether the form's submit action is pending.
+   * @selector [data-pending]
+   */
+  isPending: boolean,
+  /**
+   * The last error that occurred within the form's submit action.
+   * @selector [data-action-error]
+   */
+  actionError: unknown | null
 }
 
 export const FormContext = createContext<ContextValue<FormProps, HTMLFormElement>>(null);
+export const FormPendingContext = createContext<boolean>(false);
 
 /**
  * A form is a group of inputs that allows users to submit data to a server,
  * with support for providing field validation errors.
  */
 export const Form = forwardRef(function Form(props: FormProps, ref: ForwardedRef<HTMLFormElement>) {
   [props, ref] = useContextProps(props, ref, FormContext);
-  let {validationErrors, validationBehavior = 'native', children, className, ...domProps} = props;
+  let {validationErrors, validationBehavior = 'native', children, className, style, submitAction, action, onSubmit, ...domProps} = props;
+
+  let [onAction, isPending, actionError] = useAction(submitAction);
+  let [formError, fieldErrors] = useMemo(() => {
+    // Support errors from libraries conforming to the Standard Schema spec: https://standardschema.dev/schema
+    if (actionError && typeof actionError === 'object' && Array.isArray(actionError['issues'])) {
+      let formErrors: string[] = [];
+      let fieldErrors: Record<string, string[]> = {};
+      for (let issue of actionError['issues']) {
+        if (
+          issue &&
+          typeof issue === 'object' &&
+          typeof issue.message === 'string'
+        ) {
+          if (Array.isArray(issue.path) && issue.path.length > 0 && typeof issue.path[0] === 'string') {
+            fieldErrors[issue.path[0]] ||= [];
+            fieldErrors[issue.path[0]].push(issue.message);
+          } else {
+            formErrors.push(issue.message);
+          }
+        }
+      }
+
+      return [formErrors.length > 0 ? formErrors : null, fieldErrors];
+
+    // Alternative error shape based on Zod's flattenError result: https://zod.dev/error-formatting#zflattenerror
+    } else if (actionError && typeof actionError === 'object' && (actionError['formErrors'] || actionError['fieldErrors'])) {
+      return [actionError['formErrors'], actionError['fieldErrors']];
+    }
+
+    return [actionError, null];
+  }, [actionError]);
+
+  let renderProps = useRenderProps({
+    children,
+    className,
+    style,
+    defaultClassName: 'react-aria-Form',
+    values: {
+      isPending,
+      actionError: formError
+    }
+  });
+
   return (
-    <dom.form noValidate={validationBehavior !== 'native'} {...domProps} ref={ref} className={className || 'react-aria-Form'}>
-      <FormContext.Provider value={{...props, validationBehavior}}>
-        <FormValidationContext.Provider value={validationErrors ?? {}}>
-          {children}
-        </FormValidationContext.Provider>
-      </FormContext.Provider>
+    <dom.form
+      noValidate={validationBehavior !== 'native'}
+      {...domProps}
+      {...renderProps}
+      ref={ref}
+      data-pending={isPending || undefined}
+      data-action-error={!!formError || undefined}
+      action={action}
+      onSubmit={e => {
+        onSubmit?.(e);
+        if (onAction) {
+          e.preventDefault();
+          onAction(new FormData(e.currentTarget));
+        }
+      }}>
+      <Provider
+        values={[
+          [FormContext, {...props, validationBehavior}],
+          [FormValidationContext, validationErrors ?? fieldErrors ?? {}],
+          [AlertContext, {autoFocus: !!formError}],
+          [FormPendingContext, isPending]
+        ]}>
+        {renderProps.children}
+      </Provider>
     </dom.form>
   );
 });
diff --git a/packages/react-aria-components/stories/Form.stories.tsx b/packages/react-aria-components/stories/Form.stories.tsx
@@ -11,7 +11,9 @@
  */
 
 import {action} from 'storybook/actions';
+import {Alert} from '../src/Alert';
 import {Button} from '../src/Button';
+import {FieldError} from '../src/FieldError';
 import {Form} from '../src/Form';
 import {Input} from '../src/Input';
 import {Label} from '../src/Label';
@@ -77,3 +79,51 @@ export const FormAutoFillExample: FormStory = () => {
   );
 };
 
+export const FormErrorExample: FormStory = () => {
+  return (
+    <Form
+      style={{display: 'flex', flexDirection: 'column', gap: 16, alignItems: 'start'}}
+      submitAction={async (formData) => {
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        
+        let name = formData.get('name');
+        if (!name) {
+          throw {
+            issues: [{
+              message: 'Enter your name',
+              path: ['name']
+            }]
+          };
+        }
+
+        if (name === 'test') {
+          throw 'Could not create account. Please try again later.';
+        }
+      }}>
+      {({actionError}) => (<>
+        <p>Submit an empty value for a field-level error.<br />Enter "test" to see a form-level error.</p>
+        {actionError && 
+          <Alert
+            style={({isFocusVisible}) => ({
+              border: '2px solid red',
+              padding: 16,
+              outline: isFocusVisible ? '2px solid blue' : undefined,
+              outlineOffset: 2
+            })}>
+            {String(actionError)}
+          </Alert>
+        }
+        <TextField
+          name="name"
+          style={{display: 'flex', flexDirection: 'column'}}>
+          <Label>Name</Label>
+          <Input />
+          <FieldError style={{color: 'red'}} />
+        </TextField>
+        <Button type="submit">
+          {({isPending}) => isPending ? 'Submitting...' : 'Submit'}
+        </Button>
+      </>)}
+    </Form>
+  );
+};
diff --git a/rfcs/2026-async-react.md b/rfcs/2026-async-react.md
@@ -207,6 +207,51 @@ function App() {
 }
 ```
 
+#### Form errors
+
+When an error is thrown in a form's `submitAction`, it will be available via the `actionError` render prop. This can be displayed to the user by rendering an `<Alert>`, which will be focused and announced by screen readers. For field-level errors (e.g. server validation), a special error object compatible with [Standard Schema](https://standardschema.dev/schema) could be supported, allowing these errors to be automatically propagated to the correct fields (as we support via the `validationErrors` prop today).
+
+**Note**: This proposes a separate `submitAction` prop rather than overloading the existing `action` prop supported by React. `submitAction` has a few differences from `action`:
+
+* Errors thrown during the action are caught and passed to the `actionError` render prop.
+* The pending state is automatically passed to the form's submit button. Alternatively we could use React's [useFormStatus](https://react.dev/reference/react-dom/hooks/useFormStatus) hook for that, but this has [bugs](https://github.com/facebook/react/issues/30368) at the moment.
+* The form is not automatically reset after the action completes. This is a [controversial](https://github.com/facebook/react/issues/29034) behavior that is often unwanted (e.g. when errors occur). If a reset is desired, it can be triggered manually via `ReactDOM.requestFormReset`.
+
+```tsx
+function App() {
+  return (
+    <Form
+      submitAction={async (formData) => {
+        let email = formData.get('email');
+        if (!await isAccountAvailable(email)) {
+          throw {
+            issues: [{
+              message: 'An account with that email already exists',
+              path: ['email']
+            }]
+          }
+        }
+
+        try {
+          await createAccount(email);
+        } catch {
+          throw 'Could not create account';
+        }
+      }}>
+      {({actionError}) => (
+        <>
+          {actionError &&
+            <Alert>{String(actionError)}</Alert>
+          }
+          <TextField name="email" />
+          <Button type="submit">Submit</Button>
+        </>
+      )}
+    </Form>
+  );
+}
+```
+
 ## Documentation
 
 We'll add new examples to our documentation showing how to use action props, and add pending states to components in our starter kits.
