From f1aafc6ce79448821af41632467b9837f2e35a10 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 4 Nov 2025 18:39:57 -0800
Subject: [PATCH] docs: Add Forms and Customization guides (#9141)

* docs: Add Forms and Customization guides

* thanks linter, i hate it
---
 .../pages/react-aria/customization.mdx        | 352 ++++++++++++
 .../dev/s2-docs/pages/react-aria/forms.mdx    | 499 ++++++++++++++++++
 .../dev/s2-docs/pages/react-aria/styling.mdx  |  28 +-
 packages/dev/s2-docs/pages/s2/forms.mdx       | 214 ++++----
 packages/dev/s2-docs/src/ComponentCard.tsx    |   1 +
 5 files changed, 974 insertions(+), 120 deletions(-)
 create mode 100644 packages/dev/s2-docs/pages/react-aria/customization.mdx
 create mode 100644 packages/dev/s2-docs/pages/react-aria/forms.mdx

diff --git a/packages/dev/s2-docs/pages/react-aria/customization.mdx b/packages/dev/s2-docs/pages/react-aria/customization.mdx
new file mode 100644
index 00000000000..e0b5afbe528
--- /dev/null
+++ b/packages/dev/s2-docs/pages/react-aria/customization.mdx
@@ -0,0 +1,352 @@
+import {Layout} from '../../src/Layout';
+export default Layout;
+
+import docs from 'docs:react-aria-components';
+
+export const section = 'Guides';
+export const description = 'Building custom component patterns';
+
+# Customization
+
+React Aria Components is built using a flexible and composable API that you can extend to build new patterns. If you need even more customizability, drop down to the lower level Hook-based API for even more control over rendering and behavior. Mix and match as needed.
+
+## Contexts
+
+The React Aria Components API is designed around composition. Components are reused between patterns to build larger composite components. For example, there is no dedicated `NumberFieldIncrementButton` or `SelectPopover` component. Instead, the standalone [Button](Button.html) and [Popover](Popover.html) components are reused within [NumberField](NumberField.html) and [Select](Select.html). This reduces the amount of duplicate styling code you need to write and maintain, and provides powerful composition capabilities you can use in your own components.
+
+```tsx
+<NumberField>
+  <Label>Width</Label>
+  <Group>
+    <Input />
+    <Button slot="increment">+</Button>
+    <Button slot="decrement">-</Button>
+  </Group>
+</NumberField>
+```
+
+React Aria Components automatically provide behavior to their children by passing event handlers and other attributes via context. For example, the increment and decrement buttons in a `NumberField` receive `onPress` handlers that update the value. Keeping each element of a component separate enables full styling, layout, and DOM structure control, and contexts ensure that accessibility and behavior are taken care of on your behalf.
+
+This architecture also enables you to reuse React Aria Components in your own custom patterns, or even replace one part of a component with your own custom implementation without rebuilding the whole pattern from scratch.
+
+### Custom patterns
+
+Each React Aria Component exports a corresponding context that you can use to build your own compositional APIs similar to the built-in components. These accept the component's props as a value. The local component props are merged with the ones passed via context, with the local props taking precedence (see [mergeProps](mergeProps.html)).
+
+This example shows a `FieldGroup` component that renders a group of text fields. The entire group can be marked as disabled via the `isDisabled` prop, which is passed to all child text fields via the `TextFieldContext` provider.
+
+```tsx
+import {TextFieldContext} from 'react-aria-components';
+
+interface FieldGroupProps {
+  children?: React.ReactNode,
+  isDisabled?: boolean
+}
+
+function FieldGroup({children, isDisabled}: FieldGroupProps) {
+  return (
+    /*- begin highlight -*/
+    <TextFieldContext.Provider value={{isDisabled}}>
+    {/*- end highlight -*/}
+      {children}
+    </TextFieldContext.Provider>
+  );
+}
+```
+
+Any `TextField` component you place inside a `FieldGroup` will automatically receive the `isDisabled` prop from the group, including those that are deeply nested inside other components.
+
+```tsx
+<FieldGroup isDisabled={isSubmitting}>
+  <MyTextField label="Name" />
+  <MyTextField label="Email" />
+  <CreditCardFields />
+</FieldGroup>
+```
+
+### Slots
+
+Some patterns include multiple instances of the same component, which are distinguished by the `slot` prop. Slots are named children within a component that have separate behaviors and [styles](styling.html#slots). Separate props can be sent to slots by providing an object with keys for each slot name to the component's context provider.
+
+This example shows a `Stepper` component with slots for its increment and decrement buttons.
+
+```tsx
+function Stepper({children}) {
+  let [value, setValue] = React.useState(0);
+
+  return (
+    <ButtonContext.Provider
+      value={{
+        slots: {
+          increment: {
+            onPress: () => setValue(value + 1)
+          },
+          decrement: {
+            onPress: () => setValue(value - 1)
+          }
+        }
+      }}>
+      {children}
+    </ButtonContext.Provider>
+  );
+}
+
+<Stepper>
+  <Button slot="increment">⬆</Button>
+  <Button slot="decrement">⬇</Button>
+</Stepper>
+```
+
+#### Default slot
+
+The default slot is used to provide props to a component without specifying a slot name. This is used by children without a `slot` prop. This example passes a specific class name to a standard button child and to a button child with a slot named "end".
+
+```tsx
+import {Button, ButtonContext, DEFAULT_SLOT} from 'react-aria-components';
+
+function MyCustomComponent({children}) {
+  return (
+    <ButtonContext.Provider
+      value={{
+        slots: {
+          [DEFAULT_SLOT]: {
+            className: "default-button"
+          },
+          end: {
+            className: "end-button"
+          }
+        }
+      }}>
+      {children}
+    </ButtonContext.Provider>
+  );
+}
+
+<MyCustomComponent>
+  {/* Consumes the props passed to the default slot */}
+  <Button>Click me</Button>
+  {/* Consumes the props passed to the "end" slot */}
+  <Button slot="end">Click me</Button>
+</MyCustomComponent>
+```
+
+### Provider
+
+The `Provider` component is a utility that makes it easier to provide multiple React contexts without manually nesting them. This can be achieved by passing pairs of contexts and values as an array to the `values` prop.
+
+```tsx
+import {Provider, ButtonContext, InputContext} from 'react-aria-components';
+
+<Provider
+  values={[
+    [ButtonContext, {/* ... */}],
+    [InputContext, {/* ... */}]
+  ]}>
+  {/* ... */}
+</Provider>
+```
+
+This is equivalent to:
+
+```tsx
+<ButtonContext.Provider value={{/* ... */}}>
+  <InputContext.Provider value={{/* ... */}}>
+    {/* ... */}
+  </InputContext.Provider>
+</ButtonContext.Provider>
+```
+
+### Consuming contexts
+
+You can also consume from contexts provided by React Aria Components in your own custom components. This allows you to replace a component used as part of a larger pattern with a custom implementation. For example, you could consume from `LabelContext` in a custom label component to make it compatible with React Aria Components.
+
+#### useContextProps
+
+The <TypeLink links={docs.links} type={docs.exports.useContextProps} /> hook merges the local props with the ones provided via context by a parent component. The local props always take precedence over the context values (see [mergeProps](mergeProps.html)). `useContextProps` supports the [slot](#slots) prop to indicate which value to consume from context.
+
+```tsx
+import type {LabelProps} from 'react-aria-components';
+import {LabelContext, useContextProps} from 'react-aria-components';
+
+const MyCustomLabel = React.forwardRef(
+  (props: LabelProps, ref: React.ForwardedRef<HTMLLabelElement>) => {
+    // Merge the local props and ref with the ones provided via context.
+    /*- begin highlight -*/
+    let [mergedProps, mergedRef] = useContextProps(props, ref, LabelContext);
+    /*- end highlight -*/
+
+    // ... your existing Label component
+    return <label {...mergedProps} ref={mergedRef} />;
+  }
+);
+```
+
+Since it consumes from `LabelContext`, `MyCustomLabel` can be used within any React Aria component instead of the built-in `Label`.
+
+```tsx
+<TextField>
+  {/*- begin highlight -*/}
+  <MyCustomLabel>Name</MyCustomLabel>
+  {/*- end highlight -*/}
+  <Input />
+</TextField>
+```
+
+#### useSlottedContext
+
+To consume a context without merging with existing props, use the <TypeLink links={docs.links} type={docs.exports.useSlottedContext} /> hook. This works like React's `useContext`, and also accepts an optional slot argument to identify which slot name to consume.
+
+```tsx
+import {useSlottedContext} from 'react-aria-components';
+
+// Consume the un-slotted value.
+let buttonContext = useSlottedContext(ButtonContext);
+
+// Consume the value for a specific slot name.
+let incrementButtonContext = useSlottedContext(ButtonContext, 'increment');
+```
+
+### Accessing state
+
+Most React Aria components compose other components in their children to build larger patterns. However, some components are made up of more tightly coupled children. For example, [Calendar](Calendar.html) includes children such as `CalendarGrid` and `CalendarCell` that cannot be used standalone. These components access the state from their parent via context.
+
+You can access the state from a parent component via the same contexts in order to build your own custom children. This example shows a `CalendarValue` component that displays the currently selected date from a calendar as a formatted string.
+
+```tsx
+import {CalendarStateContext} from 'react-aria-components';
+import {useDateFormatter} from 'react-aria';
+import {getLocalTimeZone} from '@internationalized/date';
+
+function CalendarValue() {
+  /*- begin highlight -*/
+  let state = React.useContext(CalendarStateContext)!;
+  /*- end highlight -*/
+  let date = state.value?.toDate(getLocalTimeZone());
+  let {format} = useDateFormatter();
+  let formatted = date ? format(date) : 'None';
+  return `Selected date: ${formatted}`;
+}
+```
+
+This enables a `<CalendarValue>` to be placed inside a `<Calendar>` to display the current value.
+
+```tsx
+<Calendar>
+  {/* ... */}
+  {/*- begin highlight -*/}
+  <CalendarValue />
+  {/*- end highlight -*/}
+</Calendar>
+```
+
+## Hooks
+
+If you need to customize things even further, such as overriding behavior, intercepting events, or customizing DOM structure, you can drop down to the lower level Hook-based API. Hooks only provide behavior and leave all rendering to you. This gives you more control and flexibility, but requires additional glue code to set up.
+
+React Aria Components and Hooks can be used together, allowing you to mix and match depending on the level of customization you require. We recommend starting with the component API by default, and only dropping down to hooks when you need to customize something that the component API does not allow.
+
+Some potential use cases for Hooks are:
+
+* Overriding which DOM element a component renders
+* Intercepting a DOM event to apply conditional logic
+* Overriding internal state management behavior
+* Customizing overlay positioning
+* Removing unused features to reduce bundle size
+
+### Setup
+
+As described [above](#contexts), each React Aria component exports a corresponding context. You can build a custom implementation of a component using Hooks by consuming from the relevant context with <TypeLink links={docs.links} type={docs.exports.useContextProps} />.
+
+This example shows how a custom checkbox could be set up using `CheckboxContext` from `react-aria-components` and the [useCheckbox](https://react-spectrum.adobe.com/react-aria/useCheckbox.html) hook from `react-aria`.
+
+```tsx
+import type {CheckboxProps} from 'react-aria-components';
+import {CheckboxContext, useContextProps} from 'react-aria-components';
+import {useToggleState} from 'react-stately';
+import {useCheckbox} from 'react-aria';
+
+const MyCheckbox = React.forwardRef((props: CheckboxProps, ref: React.ForwardedRef<HTMLInputElement>) => {
+  // Merge the local props and ref with the ones provided via context.
+  ///- begin highlight -///
+  let [mergedProps, mergedRef] = useContextProps(props, ref, CheckboxContext);
+  ///- end highlight -///
+
+  // Follow the hook docs and implement your customizations...
+  let state = useToggleState(mergedProps);
+  let {inputProps} = useCheckbox(mergedProps, state, mergedRef);
+  return <input {...inputProps} ref={mergedRef} />;
+});
+```
+
+Since `MyCheckbox` consumes from `CheckboxContext` it can be used within other React Aria Components in place of the built-in `Checkbox`, such as within a [Table](Table.html) or [GridList](GridList.html). This lets you provide a custom checkbox implementation without rewriting all other React Aria Components you might use it in.
+
+```tsx
+<GridList>
+  <GridListItem>
+    {/*- begin highlight -*/}
+    <MyCheckbox slot="selection" />
+    {/*- end highlight -*/}
+    {/* ... */}
+  </GridListItem>
+</GridList>
+```
+
+### Reusing children
+
+You can also provide values for React Aria Components from a Hook-based implementation. This allows you to customize the parent component of a larger pattern, while reusing the existing implementations of the child elements from React Aria Components.
+
+This example shows how a custom number field could be set up. First, follow the docs for [useNumberField](useNumberField.html), and then use [Provider](#provider) to send values returned by the hook to each of the child elements via their corresponding contexts.
+
+```tsx
+import type {NumberFieldProps} from 'react-aria-components';
+import {Provider, GroupContext, InputContext, LabelContext, ButtonContext} from 'react-aria-components';
+import {useNumberFieldState} from 'react-stately';
+import {useNumberField, useLocale} from 'react-aria';
+
+function CustomNumberField(props: NumberFieldProps) {
+  // Follow the hook docs...
+  let {locale} = useLocale();
+  let state = useNumberFieldState({...props, locale});
+  let ref = useRef<HTMLInputElement>(null);
+  let {
+    labelProps,
+    groupProps,
+    inputProps,
+    incrementButtonProps,
+    decrementButtonProps
+  } = useNumberField(props, state, ref);
+
+  // Provide values for the child components via context.
+  return (
+    /*- begin highlight -*/
+    <Provider
+      values={[
+        [GroupContext, groupProps],
+        [InputContext, {...inputProps, ref}],
+        [LabelContext, labelProps],
+        [ButtonContext, {
+          slots: {
+            increment: incrementButtonProps,
+            decrement: decrementButtonProps
+          }
+        }]
+      ]}>
+      {props.children}
+    </Provider>
+    /*- end highlight -*/
+  );
+}
+```
+
+Because `CustomNumberField` provides values for the `Group`, `Input`, `Label`, and `Button` components via context, the implementations from React Aria Components can be reused.
+
+```tsx
+<CustomNumberField>
+  <Label>Width</Label>
+  <Group>
+    <Input />
+    <Button slot="increment">+</Button>
+    <Button slot="decrement">-</Button>
+  </Group>
+</CustomNumberField>
+```
diff --git a/packages/dev/s2-docs/pages/react-aria/forms.mdx b/packages/dev/s2-docs/pages/react-aria/forms.mdx
new file mode 100644
index 00000000000..171f975cd51
--- /dev/null
+++ b/packages/dev/s2-docs/pages/react-aria/forms.mdx
@@ -0,0 +1,499 @@
+import {Layout} from '../../src/Layout';
+export default Layout;
+
+import {InlineAlert, Heading, Content} from '@react-spectrum/s2';
+
+export const section = 'Guides';
+export const tags = ['forms', 'validation'];
+export const description = 'Building accessible forms with React Aria';
+
+# Forms
+
+<PageDescription>Forms allow users to enter and submit data, and provide them with feedback along the way. React Aria includes many components that integrate with HTML forms, with support for custom validation and styling.</PageDescription>
+
+## Labels and help text
+
+Accessible forms start with clear, descriptive labels for each field. Rendering a `<Label>` within a field automatically associates it with the input. Additional context can also be added via a secondary `description` slot. The label and description are announced by screen readers when the field is focused.
+
+```tsx render expanded
+"use client";
+import {TextField, Label, Input, Text} from 'react-aria-components';
+
+<TextField type="password">
+  {/*- begin highlight -*/}
+  <Label>Password</Label>
+  {/*- end highlight -*/}
+  <Input className="react-aria-Input inset" placeholder="Choose a password" />
+  {/*- begin highlight -*/}
+  <Text slot="description" className="field-description">
+    Password must be at least 8 characters.
+  </Text>
+  {/*- end highlight -*/}
+</TextField>
+```
+
+Most fields should have a visible label. In rare exceptions, the `aria-label` or `aria-labelledby` attribute must be provided for assistive technologies.
+
+## Submitting data
+
+How you submit form data depends on your framework, application, and server. By default, HTML forms are submitted by the browser using a full page refresh. You can take control of form submission using the `action` prop or `onSubmit` event.
+
+### Uncontrolled forms
+
+When using React 19, use the `action` prop to handle form submission. This receives a [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object containing the values for each form field. In React 18 or earlier, use the `onSubmit` event instead.
+
+<ExampleSwitcher type={null} examples={['React 19', 'React 18']}>
+
+```tsx render
+"use client";
+import {Form} from 'vanilla-starter/Form';
+import {TextField} from 'vanilla-starter/TextField';
+import {Button} from 'vanilla-starter/Button';
+
+<Form
+  /*- begin highlight -*/
+  action={formData => {
+    let name = formData.get('name');
+    alert(`Hello, ${name}!`);
+  }}>
+  {/*- end highlight -*/}
+  <TextField name="name" label="Name" placeholder="Enter your full name" />
+  <Button type="submit">Submit</Button>
+</Form>
+```
+
+```tsx render
+"use client";
+import {Form} from 'vanilla-starter/Form';
+import {TextField} from 'vanilla-starter/TextField';
+import {Button} from 'vanilla-starter/Button';
+
+<Form
+  /*- begin highlight -*/
+  onSubmit={event => {
+    // Prevent default browser page refresh.
+    event.preventDefault();
+
+    // Get data from form.
+    let formData = new FormData(event.target);
+    let name = formData.get('name');
+    alert(`Hello, ${name}!`);
+
+    // Reset form after submission.
+    event.target.reset();
+  }}>
+  {/*- end highlight -*/}
+  <TextField name="name" label="Name" placeholder="Enter your full name" />
+  <Button type="submit">Submit</Button>
+</Form>
+```
+
+</ExampleSwitcher>
+
+### Controlled forms
+
+By default, all React Aria components are uncontrolled, which means that the state is stored internally on your behalf. To synchronize the value with another part of the UI as the user edits, use the `value` and `onChange` props with the [useState](https://react.dev/reference/react/useState) hook.
+
+```tsx render
+'use client';
+import {Form} from 'vanilla-starter/Form';
+import {TextField} from 'vanilla-starter/TextField';
+import {Button} from 'vanilla-starter/Button';
+import {useState} from 'react';
+
+function Example() {
+  /*- begin highlight -*/
+  let [name, setName] = useState('');
+  /*- end highlight -*/
+
+  return (
+    <Form
+      action={() => {
+        // Submit data to your backend API...
+        alert(name)
+      }}>
+      <TextField
+        label="Name"
+        placeholder="Enter your name"
+        /*- begin highlight -*/
+        value={name}
+        onChange={setName} />
+      {/*- end highlight -*/}
+      <div>You entered: {name}</div>
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+## Validation
+
+Well-designed form validation assists the user with specific, helpful error messages without confusing them with unnecessary errors for partial input. React Aria supports native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and integration with server-side validation errors.
+
+### Constraint validation
+
+All React Aria form components integrate with HTML [constraint validation](https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation). This allows you to define constraints on each field such as required, minimum and maximum values, text formats such as email addresses, and custom regular expression patterns. These constraints are checked by the browser when the user commits changes to the value (e.g. on blur) or submits the form.
+
+Use the `FieldError` component to display validation errors with custom styles rather than the browser's default UI.
+
+```tsx render
+"use client";
+import {TextField, Label, Input, FieldError} from 'react-aria-components';
+import {Form} from 'vanilla-starter/Form';
+import {Button} from 'vanilla-starter/Button';
+
+<Form>
+  {/*- begin highlight -*/}
+  <TextField name="email" type="email" isRequired>
+  {/*- end highlight -*/}
+    <Label>Email</Label>
+    <Input className="react-aria-Input inset" placeholder="Enter your email" />
+    {/*- begin highlight -*/}
+    <FieldError />
+    {/*- end highlight -*/}
+  </TextField>
+  <Button type="submit">Submit</Button>
+</Form>
+```
+
+Supported constraints include:
+
+* `isRequired` indicates that a field must have a value before the form can be submitted.
+* `minValue` and `maxValue` specify the minimum and maximum value in a date picker or number field.
+* `minLength` and `maxLength` specify the minimum and length of text input.
+* `pattern` provides a custom [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) that a text input must conform to.
+* `type="email"` and `type="url"` provide builtin validation for email addresses and URLs.
+
+See each component's documentation for more details on the supported validation props.
+
+### Customizing error messages
+
+By default, the `FieldError` component displays the error message provided by the browser, which is localized in the user's preferred language. You can customize these messages by providing a render prop function to `FieldError`. This receives a list of error strings along with a [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) object describing why the field is invalid.
+
+```tsx render
+"use client";
+import {TextField, Label, Input, FieldError} from 'react-aria-components';
+import {Form} from 'vanilla-starter/Form';
+import {Button} from 'vanilla-starter/Button';
+
+<Form>
+  <TextField name="name" isRequired>
+    <Label>Name</Label>
+    <Input className="react-aria-Input inset" placeholder="Enter your name" />
+    {/*- begin highlight -*/}
+    <FieldError>
+      {({validationDetails}) => (
+        validationDetails.valueMissing ? 'Please enter a name.' : ''
+      )}
+    </FieldError>
+    {/*- end highlight -*/}
+  </TextField>
+  <Button type="submit">Submit</Button>
+</Form>
+```
+
+<InlineAlert variant="informative">
+  <Heading>Localization</Heading>
+  <Content>The default error messages are localized by the browser using the browser/operating system language setting. React Aria's [I18nProvider](I18nProvider.html) has no effect on validation errors.</Content>
+</InlineAlert>
+
+### Custom validation
+
+To implement custom validation rules, pass a function to the `validate` prop. This receives the current field value, and can return one or more error messages. These are displayed to the user after the value is committed (e.g. on blur) to avoid distracting them on each keystroke.
+
+```tsx render
+"use client";
+import {Form} from 'vanilla-starter/Form';
+import {TextField} from 'vanilla-starter/TextField';
+import {Button} from 'vanilla-starter/Button';
+
+<Form>
+  <TextField
+    label="Username"
+    placeholder="Choose a username"
+    /*- begin highlight -*/
+    validate={value => value === 'admin' ? 'Nice try!' : null} />
+    {/*- end highlight -*/}
+  <Button type="submit">Submit</Button>
+</Form>
+```
+
+### Realtime validation
+
+By default, validation errors are displayed after the value is committed (e.g. on blur), or when the form is submitted. This avoids confusing the user with irrelevant errors while they are still entering a value.
+
+In some cases, validating in realtime can be helpful, such as when meeting password requirements. To implement this, make the field value [controlled](#controlled-forms), and set the `isInvalid` prop and error message appropriately.
+
+```tsx render
+'use client';
+import {Form} from 'vanilla-starter/Form';
+import {TextField} from 'vanilla-starter/TextField';
+import {Button} from 'vanilla-starter/Button';
+import {useState} from 'react';
+
+function Example() {
+  let [password, setPassword] = useState('');
+  let error;
+  if (password.length < 8) {
+    error = 'Password must be 8 characters or more.';
+  } else if ((password.match(/[A-Z]/g) ?? []).length < 2) {
+    error = 'Password must include at least 2 upper case letters';
+  } else if ((password.match(/[^a-z]/ig) ?? []).length < 2) {
+    error = 'Password must include at least 2 symbols.';
+  }
+
+  return (
+    <TextField
+      label="Password"
+      placeholder="Choose a password"
+      /*- begin highlight -*/
+      isInvalid={!!error}
+      errorMessage={error}
+      /*- end highlight -*/
+      value={password}
+      onChange={setPassword} />
+  );
+}
+```
+
+By default, invalid fields block forms from being submitted. To avoid this, use `validationBehavior="aria"`, which will only mark the field as required and invalid for assistive technologies, and will not prevent form submission.
+
+### Server validation
+
+Client side validation is useful to give the user immediate feedback, but data should always be validated on the backend for security and reliability. Your business logic may also include rules which cannot be validated on the frontend.
+
+To display server validation errors, set the the `validationErrors` prop on the [Form](Form.html) component. This accepts an object that maps each field's `name` prop to one or more error messages. These are displayed as soon as the `validationErrors` prop is set, and cleared after the user modifies each field's value.
+
+```tsx render
+'use client';
+import {Form} from 'vanilla-starter/Form';
+import {TextField} from 'vanilla-starter/TextField';
+import {Button} from 'vanilla-starter/Button';
+import {useActionState} from 'react';
+
+function action(prevState, formData: FormData) {
+  return {
+    values: Object.fromEntries(formData),
+    errors: {
+      username: 'Sorry, this username is taken.'
+    }
+  };
+}
+
+function Example() {
+  let [{values, errors}, formAction] = useActionState(action, {});
+
+  return (
+    <Form
+      validationBehavior="native"
+      action={formAction}
+      /*- begin highlight -*/
+      validationErrors={errors}>
+      {/*- end highlight -*/}
+      <TextField
+        label="Username"
+        name="username"
+        placeholder="Enter your username"
+        defaultValue={values?.username}
+        isRequired />
+      <TextField
+        label="Password"
+        name="password"
+        placeholder="Enter your password"
+        defaultValue={values?.password}
+        type="password"
+        isRequired />
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+#### Schema validation
+
+React Aria is compatible with errors returned from schema validation libraries like [Zod](https://zod.dev/), which are often used for server-side form validation. Use the [flatten](https://zod.dev/ERROR_HANDLING?id=flattening-errors) method to get a list of errors for each field and return this as part of your HTTP response.
+
+```tsx
+// In your server...
+import {z} from 'zod';
+
+const schema = z.object({
+  name: z.string().min(1),
+  age: z.coerce.number().positive()
+});
+
+function handleRequest(formData: FormData) {
+  let result = schema.safeParse(Object.fromEntries(formData));
+  if (!result.success) {
+    return {
+      /*- begin highlight -*/
+      errors: result.error.flatten().fieldErrors
+      /*- end highlight -*/
+    };
+  }
+
+  // Do stuff...
+
+  return {
+    errors: {}
+  };
+}
+```
+
+<InlineAlert variant="informative">
+  <Heading>Localization</Heading>
+  <Content>Error message localization is best done on the server rather than on the client to avoid large bundles. You can submit the user's locale as part of the form data if needed, and use a library like [zod-i18n](https://github.com/aiji42/zod-i18n) to translate the errors.</Content>
+</InlineAlert>
+
+#### React Server Functions
+
+[Server Functions](https://react.dev/reference/rsc/server-functions), marked with the `"use server"` directive, allow client components to call async functions executed on the server in supported frameworks (e.g. Next.js).
+
+```tsx
+// app/actions.ts
+/*- begin highlight -*/
+'use server';
+/*- end highlight -*/
+
+export async function createTodo(prevState: any, formData: FormData) {
+  try {
+    // Create the todo...
+  } catch (err) {
+    return {
+      errors: {
+        todo: 'Invalid todo.'
+      }
+    };
+  }
+}
+```
+
+Server functions can be imported into client components and passed to the Form `action` prop. Use the [useActionState](https://react.dev/reference/react/useActionState) hook to access the return value, which may include validation errors.
+
+```tsx
+// app/add-form.tsx
+'use client';
+
+import {useActionState} from 'react';
+import {Form} from 'vanilla-starter/Form';
+import {TextField} from 'vanilla-starter/TextField';
+import {Button} from 'vanilla-starter/Button';
+import {createTodo} from './actions';
+
+export function AddForm() {
+  /*- begin highlight -*/
+  let [{errors}, formAction] = useActionState(createTodo, {errors: {}});
+  /*- end highlight -*/
+
+  return (
+    /*- begin highlight -*/
+    <Form action={formAction} validationErrors={errors}>
+    {/*- end highlight -*/}
+      <TextField label="Task" name="todo" />
+      <Button type="submit">Add</Button>
+    </Form>
+  );
+}
+```
+
+#### React Router actions
+
+[React Router actions](https://reactrouter.com/start/framework/actions) handle form submissions. Use the [useSubmit](https://remix.run/docs/en/main/hooks/use-submit) hook to submit data to the server. An action may return data such as validation errors via the `actionData` route component prop.
+
+```tsx
+// app/routes/signup.tsx
+import {useSubmit} from 'react-router';
+import {Form} from 'vanilla-starter/Form';
+import {TextField} from 'vanilla-starter/TextField';
+import {Button} from 'vanilla-starter/Button';
+
+export default function SignupForm({actionData}: Route.ComponentProps) {
+  let submit = useSubmit();
+
+  return (
+    <Form
+      /*- begin highlight -*/
+      method="post"
+      onSubmit={e => {
+        e.preventDefault();
+        submit(e.currentTarget);
+      }}
+      validationErrors={actionData?.errors}>
+      {/*- end highlight -*/}
+      <TextField label="Username" name="username" isRequired />
+      <TextField label="Password" name="password" type="password" isRequired />
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+
+export async function action({request}: Route.ActionArgs) {
+  try {
+    // Validate data and perform action...
+  } catch (err) {
+    return {
+      errors: {
+        /*- begin highlight -*/
+        username: 'Sorry, this username is taken.'
+        /*- end highlight -*/
+      }
+    };
+  }
+}
+```
+
+## Form libraries
+
+In most cases, uncontrolled forms with the builtin validation features are sufficient. However, if you are building a truly complex form, or integrating React Aria components into an existing form, a separate form library such as [React Hook Form](https://react-hook-form.com/) or [Formik](https://formik.org/) may be helpful.
+
+### React Hook Form
+
+[React Hook Form](https://react-hook-form.com/) is a popular form library for React. It is primarily designed to work directly with plain HTML input elements, but supports custom form components like the ones in React Aria as well.
+
+Use the [Controller](https://react-hook-form.com/docs/usecontroller/controller) component from React Hook Form to integrate React Aria components. Pass the props for the `field` render prop through to the React Aria component you're using, and use the `fieldState` to get validation errors to display.
+
+```tsx
+import {useForm, Controller} from 'react-hook-form';
+import {Form} from 'vanilla-starter/Form';
+import {TextField} from 'vanilla-starter/TextField';
+import {Button} from 'vanilla-starter/Button';
+
+function App() {
+  let {handleSubmit, control} = useForm({
+    defaultValues: {
+      name: '',
+    },
+  });
+  let onSubmit = (data) => {
+    // Call your API here...
+  };
+
+  return (
+    <Form onSubmit={handleSubmit(onSubmit)}>
+      <Controller
+        control={control}
+        name="name"
+        rules={{ required: 'Name is required.' }}
+        render={({
+          field: { name, value, onChange, onBlur, ref },
+          fieldState: { invalid, error },
+        }) => (
+          <TextField
+            label="Name"
+            name={name}
+            value={value}
+            onChange={onChange}
+            onBlur={onBlur}
+            ref={ref}
+            isRequired
+            // Let React Hook Form handle validation instead of the browser.
+            validationBehavior="aria"
+            isInvalid={invalid}
+            errorMessage={error?.message} />
+        )} />
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
diff --git a/packages/dev/s2-docs/pages/react-aria/styling.mdx b/packages/dev/s2-docs/pages/react-aria/styling.mdx
index c1b480a52ae..f880c30ca71 100644
--- a/packages/dev/s2-docs/pages/react-aria/styling.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/styling.mdx
@@ -9,7 +9,7 @@ export const description = 'Styling in React Aria';
 
 # Styling
 
-<PageDescription>React Aria Components do not include any styles by default, allowing you to build custom designs to fit your application or design system using any styling solution.</PageDescription>
+<PageDescription>React Aria does not include any styles by default, allowing you to build custom designs to fit your application or design system using any styling solution.</PageDescription>
 
 ## Class names
 
@@ -33,7 +33,7 @@ A custom `className` can also be specified on any component. This overrides the
 
 ## States
 
-Components often support multiple UI states (e.g. pressed, hovered, selected, etc.). React Aria Components exposes states using data attributes, which are like custom pseudo classes.
+React Aria exposes UI states such as pressed, hovered, and selected using data attributes, which are like custom pseudo classes.
 
 ```css
 .react-aria-ListBoxItem[data-selected] {
@@ -113,7 +113,7 @@ Some patterns include multiple instances of the same component, for example the
 
 ## CSS variables
 
-Some components provide CSS variables that you can use in your styling code. For example, the [Select](Select.html) component provides a `--trigger-width` variable on the popover. You can use this to make the width of the popover match the width of the button.
+Some components provide CSS variables that you can use in your styling code. For example, [Popover](Popover.html) provides a `--trigger-width` variable, which can be used to make the width of the popover match the width of its trigger.
 
 ```css
 .react-aria-Popover {
@@ -123,7 +123,7 @@ Some components provide CSS variables that you can use in your styling code. For
 
 ## Tailwind CSS
 
-[Tailwind CSS](https://tailwindcss.com) is a utility-first CSS framework for rapid styling that works great with React Aria Components. To access [states](#states), you can use [data attributes](https://tailwindcss.com/docs/hover-focus-and-other-states#data-attributes) as modifiers:
+When using Tailwind, use [data attributes](https://tailwindcss.com/docs/hover-focus-and-other-states#data-attributes) as modifiers:
 
 ```jsx
 <ListBoxItem className="data-[selected]:bg-blue-400 data-[disabled]:bg-gray-100">
@@ -147,7 +147,7 @@ Alternatively, you can use [render props](#render-props) to control which Tailwi
 To access [CSS variables](#css-variables), use Tailwind's [arbitrary value](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values) syntax.
 
 ```jsx
-<Popover className="w-[--trigger-width]">
+<Popover className="w-(--trigger-width)">
   {/* ... */}
 </Popover>
 ```
@@ -182,7 +182,7 @@ module.exports = {
   </DisclosurePanel>
 </Disclosure>
 
-With the plugin installed, you can now access all states without the `data-` prefix. If you have the [Tailwind VSCode Extension](https://tailwindcss.com/docs/editor-setup#intelli-sense-for-vs-code) installed, you'll also get autocomplete for all states in your editor.
+With the plugin installed, you can access all states without the `data-` prefix. If you have the [Tailwind VSCode Extension](https://tailwindcss.com/docs/editor-setup#intelli-sense-for-vs-code) installed, you'll also get autocomplete for all states in your editor.
 
 ```jsx
 <ListBoxItem className="selected:bg-blue-400 disabled:bg-gray-100">
@@ -202,7 +202,7 @@ Boolean states such as `data-pressed` can be styled with `pressed:` like this:
 
 ### Non-boolean states
 
-Non-boolean states follow the `{name}-{value}` pattern, so you can style an element with `data-orientation="vertical"` using `orientation-vertical:`.
+Non-boolean states follow the `{name}-{value}` pattern. For example, an element with `data-orientation="vertical"` can be styled using `orientation-vertical:`.
 
 ```jsx
 <Tabs className="orientation-vertical:flex-row">
@@ -314,9 +314,9 @@ For more complex animations, you can also apply CSS keyframe animations using th
 
 Note that unlike CSS transitions, keyframe animations are not interruptible. If the user opens and closes an overlay quickly, the animation may appear to jump to the ending state before the next animation starts.
 
-### Tailwind CSS
+### Tailwind
 
-If you are using Tailwind CSS, we recommend using the [tailwindcss-animate](https://github.com/jamiebuilds/tailwindcss-animate) plugin. This includes utilities for building common animations such as fading, sliding, and zooming.
+If you are using Tailwind, we recommend using the [tailwindcss-animate](https://github.com/jamiebuilds/tailwindcss-animate) plugin. This includes utilities for building common animations such as fading, sliding, and zooming.
 
 ```jsx
 <Popover className="data-[entering]:animate-in data-[entering]:fade-in data-[exiting]:animate-out data-[exiting]:fade-out">
@@ -326,15 +326,15 @@ If you are using Tailwind CSS, we recommend using the [tailwindcss-animate](http
 
 ### Motion
 
-[Motion](https://motion.dev) and other JavaScript animation libraries can also be used with React Aria Components. Use the [motion](https://motion.dev/docs/react-motion-component#custom-components) function to create a wrapper component that adds support for Motion's animation props.
+[Motion](https://motion.dev) and other JavaScript animation libraries can also be used with React Aria Components. Use [motion.create](https://motion.dev/docs/react-motion-component#custom-components) to create a wrapper component that adds support for Motion's animation props.
 
 ```tsx
 import {Modal, ModalOverlay} from 'react-aria-components';
 import {motion} from 'motion/react';
 
 // Create Motion wrappers.
-const MotionModal = motion(Modal);
-const MotionModalOverlay = motion(ModalOverlay);
+const MotionModal = motion.create(Modal);
+const MotionModalOverlay = motion.create(ModalOverlay);
 ```
 
 This enables using props like [animate](https://motion.dev/docs/react-motion-component#animation) with React Aria Components.
@@ -394,15 +394,13 @@ function Example() {
 }
 ```
 
-**Note**: Motion's `AnimatePresence` component may not work with React Aria overlays in all cases, so the example shown above is the recommended approach for exit animations.
-
 The [AnimatePresence](https://motion.dev/docs/react-animate-presence) component allows you to animate when items are added or removed in collection components. Use `array.map` to create children, and make sure each child has a unique `key` in addition to an `id` to ensure Motion can track it.
 
 ```tsx
 import {GridList, GridListItem} from 'react-aria-components';
 import {motion, AnimatePresence} from 'motion/react';
 
-const MotionItem = motion(GridListItem);
+const MotionItem = motion.create(GridListItem);
 
 <GridList>
   <AnimatePresence>
diff --git a/packages/dev/s2-docs/pages/s2/forms.mdx b/packages/dev/s2-docs/pages/s2/forms.mdx
index 9a904f95ba5..e923ee6db9a 100644
--- a/packages/dev/s2-docs/pages/s2/forms.mdx
+++ b/packages/dev/s2-docs/pages/s2/forms.mdx
@@ -2,10 +2,11 @@ import {Layout} from '../../src/Layout';
 export default Layout;
 
 import docs from 'docs:@react-spectrum/s2';
+import {InlineAlert, Heading, Content} from '@react-spectrum/s2';
 
 export const section = 'Guides';
 export const tags = ['forms', 'validation'];
-export const description = 'Building accessible forms with validation in React Spectrum';
+export const description = 'Building accessible forms with React Spectrum';
 
 # Forms
 
@@ -13,7 +14,7 @@ export const description = 'Building accessible forms with validation in React S
 
 ## Labels and help text
 
-Accessible forms start with clear, descriptive labels for each field. All React Spectrum form components support labeling using the `label` prop. In addition, help text associates additional context with a field such as a description or error message. The label and help text are announced by assistive technology such as screen readers when the user focuses the field.
+Accessible forms start with clear, descriptive labels for each field. Use the `label` prop to add a visible label to any field. Additional help text can also be added via the `description` prop. The label and help text are announced by screen readers when the field is focused.
 
 ```tsx render
 import {TextField} from '@react-spectrum/s2';
@@ -25,54 +26,63 @@ import {TextField} from '@react-spectrum/s2';
   description="Password must be at least 8 characters." />
 ```
 
-Most fields should have a visible label. In rare exceptions, the `aria-label` or `aria-labelledby` attribute must be provided instead to identify the element to screen readers.
+Most fields should have a visible label. In rare exceptions, the `aria-label` or `aria-labelledby` attribute must be provided for assistive technologies.
 
 ## Submitting data
 
-How you submit form data depends on your framework, application, and server. By default, HTML forms are submitted by the browser using a full page refresh. You can take control of form submission by calling `preventDefault` during the `onSubmit` event, and make an API call to submit the data however you like. Frameworks like [Next.js](https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations) and [Remix](https://remix.run/docs/en/main/components/form) also include builtin APIs to manage this for you.
+How you submit form data depends on your framework, application, and server. By default, HTML forms are submitted by the browser using a full page refresh. You can take control of form submission using the `action` prop or `onSubmit` event.
 
 ### Uncontrolled forms
 
-The simplest way to get data from a form is using the browser's [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) API during the `onSubmit` event. This can be passed directly to [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch), or converted into a regular JavaScript object using [Object.fromEntries](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries). Each field should have a `name` prop to identify it, and values will be serialized to strings by the browser.
+When using React 19, use the `action` prop to handle form submission. This receives a [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object containing the values for each form field. In React 18 or earlier, use the `onSubmit` event instead.
+
+<ExampleSwitcher type={null} examples={['React 19', 'React 18']}>
 
 ```tsx render
-'use client';
-import {Form, TextField, ButtonGroup, Button} from '@react-spectrum/s2';
-import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
-import {useState} from 'react';
+"use client";
+import {Form, TextField, Button} from '@react-spectrum/s2';
 
-function Example() {
-  let [submitted, setSubmitted] = useState(null);
+<Form
+  /*- begin highlight -*/
+  action={formData => {
+    let name = formData.get('name');
+    alert(`Hello, ${name}!`);
+  }}>
+  {/*- end highlight -*/}
+  <TextField name="name" label="Name" placeholder="Enter your full name" />
+  <Button type="submit">Submit</Button>
+</Form>
+```
+
+```tsx render
+"use client";
+import {Form, TextField, Button} from '@react-spectrum/s2';
 
+<Form
   /*- begin highlight -*/
-  let onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+  onSubmit={event => {
     // Prevent default browser page refresh.
-    e.preventDefault();
+    event.preventDefault();
 
-    // Get form data as an object.
-    let data = Object.fromEntries(new FormData(e.currentTarget));
+    // Get data from form.
+    let formData = new FormData(event.target);
+    let name = formData.get('name');
+    alert(`Hello, ${name}!`);
 
-    // Submit to your backend API...
-    setSubmitted(data);
-  };
-  /*- end highlight -*/
-
-  return (
-    <Form onSubmit={onSubmit} styles={style({maxWidth: 320})}>
-      <TextField name="name" label="Name" placeholder="Enter your name" />
-      <ButtonGroup>
-        <Button type="submit" variant="primary">Submit</Button>
-        <Button type="reset" variant="secondary">Reset</Button>
-      </ButtonGroup>
-      {submitted && <div>You submitted: <code>{JSON.stringify(submitted)}</code></div>}
-    </Form>
-  );
-}
+    // Reset form after submission.
+    event.target.reset();
+  }}>
+  {/*- end highlight -*/}
+  <TextField name="name" label="Name" placeholder="Enter your full name" />
+  <Button type="submit">Submit</Button>
+</Form>
 ```
 
+</ExampleSwitcher>
+
 ### Controlled forms
 
-By default, all React Spectrum components are uncontrolled, which means that the state is stored internally on your behalf. If you need access to the value in realtime, as the user is editing, you can make it controlled. You'll need to manage the state using React's [useState](https://react.dev/reference/react/useState) hook, and pass the current value and a change handler into each form component.
+By default, all React Spectrum components are uncontrolled, which means that the state is stored internally on your behalf. To synchronize the value with another part of the UI as the user edits, use the `value` and `onChange` props with the [useState](https://react.dev/reference/react/useState) hook.
 
 ```tsx render
 'use client';
@@ -113,19 +123,17 @@ function Example() {
 
 ## Validation
 
-Form validation is important to ensure user input is in an expected format and meets business requirements. Well-designed form validation assists the user with specific, helpful error messages without confusing and frustrating them with unnecessary errors on partial input. React Spectrum supports native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and integration with server-side validation errors.
+Well-designed form validation assists the user with specific, helpful error messages without confusing them with unnecessary errors for partial input. React Spectrum supports native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and integration with server-side validation errors.
 
-### Built-in validation
+### Constraint validation
 
 All React Spectrum form components integrate with native HTML [constraint validation](https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation). This allows you to define constraints on each field such as required, minimum and maximum values, text formats such as email addresses, and even custom regular expression patterns. These constraints are checked by the browser when the user commits changes to the value (e.g. on blur) or submits the form.
 
-To enable native validation, set the `validationBehavior="native"` prop on the [Form](Form.html) component. This example shows a required email field, which is validated by the browser and displayed with Spectrum help text.
-
 ```tsx render
 import {Form, TextField, ButtonGroup, Button} from '@react-spectrum/s2';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
-<Form validationBehavior="native" styles={style({maxWidth: 320})}>
+<Form styles={style({maxWidth: 320})}>
   <TextField
     label="Email"
     name="email"
@@ -153,14 +161,14 @@ See each component's documentation for more details on the supported validation
 
 ### Customizing error messages
 
-By default, React Spectrum displays the error message provided by the browser, which is localized in the user's preferred language. You can customize these messages by providing a function to the `errorMessage` prop. This receives a list of error strings along with a [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) object describing why the field is invalid, and should return an error message to display.
+By default, React Spectrum displays the error message provided by the browser, which is localized in the user's preferred language. You can customize these messages by providing a function to the `errorMessage` prop. This receives a list of error strings along with a [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) object describing why the field is invalid.
 
 ```tsx render
 "use client";
 import {Form, TextField, ButtonGroup, Button} from '@react-spectrum/s2';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
-<Form validationBehavior="native" styles={style({maxWidth: 320})}>
+<Form styles={style({maxWidth: 320})}>
   <TextField
     label="Name"
     name="name"
@@ -179,16 +187,21 @@ import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 </Form>
 ```
 
+<InlineAlert variant="informative">
+  <Heading>Localization</Heading>
+  <Content>The default error messages are localized by the browser using the browser/operating system language setting. React Spectrums's [Provider](Provider.html) has no effect on validation errors.</Content>
+</InlineAlert>
+
 ### Custom validation
 
-In addition to the built-in constraints, custom validation is supported by providing a function to the `validate` prop. This function receives the current field value, and can return a string or array of strings representing one or more error messages. These are displayed to the user after the value is committed (e.g. on blur) to avoid distracting them on each keystroke.
+To implement custom validation rules, pass a function to the `validate` prop. This receives the current field value, and can return one or more error messages. These are displayed to the user after the value is committed (e.g. on blur) to avoid distracting them on each keystroke.
 
 ```tsx render
 "use client";
 import {Form, TextField, ButtonGroup, Button} from '@react-spectrum/s2';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
-<Form validationBehavior="native" styles={style({maxWidth: 320})}>
+<Form styles={style({maxWidth: 320})}>
   <TextField
     label="Username"
     placeholder="Choose a username"
@@ -205,9 +218,9 @@ import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
 ### Realtime validation
 
-Usually, validation errors should be displayed to the user after the value is committed (e.g. on blur), or when the form is submitted. This avoids confusing the user with irrelevant errors while they are still entering a value.
+By default, validation errors are displayed after the value is committed (e.g. on blur), or when the form is submitted. This avoids confusing the user with irrelevant errors while they are still entering a value.
 
-In some cases, validating in realtime can be desireable, such as when meeting password requirements. This can be accomplished by making the field value [controlled](#controlled-forms), and setting the `validationState` and `errorMessage` props accordingly.
+In some cases, validating in realtime can be desireable, such as when meeting password requirements. This can be accomplished by making the field value [controlled](#controlled-forms), and setting the `isInvalid` and `errorMessage` props accordingly.
 
 ```tsx render
 'use client';
@@ -230,7 +243,7 @@ function Example() {
       label="Password"
       placeholder="Choose a password"
       /*- begin highlight -*/
-      validationState={!!error ? 'invalid' : undefined}
+      isInvalid={!!error}
       errorMessage={error}
       /*- end highlight -*/
       value={password}
@@ -239,23 +252,23 @@ function Example() {
 }
 ```
 
-By default, the `validationState="invalid"` prop does not block forms from being submitted. To block form submission, use the `validationBehavior="native"` prop on the [Form](Form.html) component.
+By default, invalid fields block forms from being submitted. To avoid this, use `validationBehavior="aria"`, which will only mark the field as required and invalid for assistive technologies, and will not prevent form submission.
 
 ### Server validation
 
-Client side validation is useful to give the user immediate feedback, but only one half of the validation story. Data should also be validated on the backend for security and reliability, and your business logic may include rules which cannot be validated on the frontend.
+Client side validation is useful to give the user immediate feedback, but data should always be validated on the backend for security and reliability. Your business logic may also include rules which cannot be validated on the frontend.
 
-React Spectrum supports displaying server validation errors by passing the `validationErrors` prop to the [Form](Form.html) component. This should be set to an object that maps each field's `name` prop to a string or array of strings representing one or more errors. These are displayed to the user as soon as the `validationErrors` prop is set, and cleared after the user modifies each field's value.
+To display server validation errors, set the the `validationErrors` prop on the [Form](Form.html) component. This accepts an object that maps each field's `name` prop to one or more error messages. These are displayed as soon as the `validationErrors` prop is set, and cleared after the user modifies each field's value.
 
 ```tsx render
 'use client';
 import {Form, TextField, ButtonGroup, Button} from '@react-spectrum/s2';
-import {useState} from 'react';
+import {useActionState} from 'react';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
-// Fake server used in this example.
-function callServer(data) {
+function action(prevState, formData: FormData) {
   return {
+    values: Object.fromEntries(formData),
     errors: {
       username: 'Sorry, this username is taken.'
     }
@@ -263,31 +276,26 @@ function callServer(data) {
 }
 
 function Example() {
-  let [errors, setErrors] = useState({});
-  let action = async (formData) => {
-    let data = Object.fromEntries(formData);
-    let result = await callServer(data)
-    setErrors(result.errors);
-  };
+  let [{values, errors}, formAction] = useActionState(action, {});
 
   return (
     <Form
-      validationBehavior="native"
       styles={style({maxWidth: 320})}
-      action={action}
+      action={formAction}
       /*- begin highlight -*/
-      validationErrors={errors}
-      /*- end highlight -*/
-    >
+      validationErrors={errors}>
+      {/*- end highlight -*/}
       <TextField
         label="Username"
         name="username"
         placeholder="Enter your username"
+        defaultValue={values?.username}
         isRequired />
       <TextField
         label="Password"
         name="password"
         placeholder="Enter your password"
+        defaultValue={values?.password}
         type="password"
         isRequired />
       <ButtonGroup>
@@ -330,23 +338,45 @@ function handleRequest(formData: FormData) {
 }
 ```
 
-Note that error message localization is also best done on the server rather than on the client to avoid large bundles. You can submit the user's locale as part of the form data if needed, and use something like [zod-i18n](https://github.com/aiji42/zod-i18n) to translate the errors into the correct language.
+<InlineAlert variant="informative">
+  <Heading>Localization</Heading>
+  <Content>Error message localization is best done on the server rather than on the client to avoid large bundles. You can submit the user's locale as part of the form data if needed, and use a library like [zod-i18n](https://github.com/aiji42/zod-i18n) to translate the errors.</Content>
+</InlineAlert>
 
 #### React Server Actions
 
-[Server Actions](https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations) are a new React feature currently supported by Next.js. They enable the client to seamlessly call the server without setting up any API routes, and integrate with forms via the `action` prop. The [useFormState](https://react.dev/reference/react-dom/hooks/useFormState) hook can be used to get the value returned by a server action after submitting a form, which may include validation errors.
+[Server Functions](https://react.dev/reference/rsc/server-functions), marked with the `"use server"` directive, allow client components to call async functions executed on the server in supported frameworks (e.g. Next.js).
+
+```tsx
+// app/actions.ts
+/*- begin highlight -*/
+'use server';
+/*- end highlight -*/
+
+export async function createTodo(prevState: any, formData: FormData) {
+  try {
+    // Create the todo...
+  } catch (err) {
+    return {
+      errors: {
+        todo: 'Invalid todo.'
+      }
+    };
+  }
+}
+```
 
 ```tsx
 // app/add-form.tsx
 'use client';
 
-import {useFormState} from 'react-dom';
+import {useActionState} from 'react';
 import {Form, TextField, ActionButton} from '@react-spectrum/s2';
 import {createTodo} from '@/app/actions';
 
 export function AddForm() {
   /*- begin highlight -*/
-  let [{errors}, formAction] = useFormState(createTodo, {errors: {}});
+  let [{errors}, formAction] = useActionState(createTodo, {errors: {}});
   /*- end highlight -*/
 
   return (
@@ -360,54 +390,28 @@ export function AddForm() {
 }
 ```
 
-```tsx
-// app/actions.ts
-'use server';
+#### React Router actions
 
-export async function createTodo(prevState: any, formData: FormData) {
-  try {
-    // Create the todo...
-  } catch (err) {
-    return {
-      errors: {
-        /*- begin highlight -*/
-        todo: 'Invalid todo.'
-        /*- end highlight -*/
-      }
-    };
-  }
-}
-```
-
-#### Remix
-
-[Remix actions](https://remix.run/docs/en/main/route/action) handle form submissions on the server. The [useSubmit](https://remix.run/docs/en/main/hooks/use-submit) hook can be used to submit data to the server, and the [useActionData](https://remix.run/docs/en/main/hooks/use-action-data) hook can be used to get the value returned by the server, which may include validation errors.
+[React Router actions](https://reactrouter.com/start/framework/actions) handle form submissions. Use the [useSubmit](https://remix.run/docs/en/main/hooks/use-submit) hook to submit data to the server. An action may return data such as validation errors via the `actionData` route component prop.
 
 ```tsx
 // app/routes/signup.tsx
-import type {ActionFunctionArgs} from '@remix-run/node';
-import {useActionData, useSubmit} from '@remix-run/react';
+import {useSubmit} from 'react-router';
 import {Form, TextField, Button} from '@react-spectrum/s2';
-import React from 'react';
 
-export default function SignupForm() {
+export default function SignupForm({actionData}: Route.ComponentProps) {
   let submit = useSubmit();
-  let onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
-    e.preventDefault();
-    submit(e.currentTarget);
-  };
-
-  /*- begin highlight -*/
-  let actionData = useActionData<typeof action>();
-  /*- end highlight -*/
 
   return (
     <Form
-      method="post"
       /*- begin highlight -*/
-      validationErrors={actionData?.errors}
-      /*- end highlight -*/
-      onSubmit={onSubmit}>
+      method="post"
+      onSubmit={e => {
+        e.preventDefault();
+        submit(e.currentTarget);
+      }}
+      validationErrors={actionData?.errors}>
+      {/*- end highlight -*/}
       <TextField label="Username" name="username" isRequired />
       <TextField label="Password" name="password" type="password" isRequired />
       <Button type="submit" variant="accent">Submit</Button>
@@ -415,7 +419,7 @@ export default function SignupForm() {
   );
 }
 
-export async function action({request}: ActionFunctionArgs) {
+export async function action({request}: Route.ActionArgs) {
   try {
     // Validate data and perform action...
   } catch (err) {
@@ -432,13 +436,13 @@ export async function action({request}: ActionFunctionArgs) {
 
 ## Form libraries
 
-In most cases, uncontrolled forms with the builtin validation features are enough. However, if you are building a truly complex form, or integrating React Spectrum components into an existing form, a separate form library such as [React Hook Form](https://react-hook-form.com/) or [Formik](https://formik.org/) may be helpful.
+In most cases, uncontrolled forms with the builtin validation features are sufficient. However, if you are building a truly complex form, or integrating React Spectrum components into an existing form, a separate form library such as [React Hook Form](https://react-hook-form.com/) or [Formik](https://formik.org/) may be helpful.
 
 ### React Hook Form
 
 [React Hook Form](https://react-hook-form.com/) is a popular form library for React. It is primarily designed to work directly with plain HTML input elements, but supports custom form components like the ones in React Spectrum as well.
 
-Since React Spectrum manages the state for components internally, you can use the [Controller](https://react-hook-form.com/docs/usecontroller/controller) component from React Hook Form to integrate React Spectrum components. Pass the props for the `field` render prop through to the React Spectrum component you're using, and use the `fieldState` to get validation errors to display.
+Use the [Controller](https://react-hook-form.com/docs/usecontroller/controller) component from React Hook Form to integrate React Spectrum components. Pass the props for the `field` render prop through to the React Spectrum component you're using, and use the `fieldState` to get validation errors to display.
 
 ```tsx
 import {useForm, Controller} from 'react-hook-form'
diff --git a/packages/dev/s2-docs/src/ComponentCard.tsx b/packages/dev/s2-docs/src/ComponentCard.tsx
index 5f26d300d16..407bd5eb7dc 100644
--- a/packages/dev/s2-docs/src/ComponentCard.tsx
+++ b/packages/dev/s2-docs/src/ComponentCard.tsx
@@ -146,6 +146,7 @@ const componentIllustrations: Record<string, React.ComponentType | undefined> =
   'FileTrigger': FileTriggerSvg,
   'FocusScope': FocusScopeSvg,
   'Form': FormSvg,
+  'Forms': FormSvg,
   'GridList': ListViewSvg, // GridList -> ListView
   'Group': GroupSvg,
   'Icons': IconsSvg,