From 8ee5ebc745d8c54ecc05b648db436120c8821dde Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Thu, 2 Oct 2025 21:25:41 -0500
Subject: [PATCH 01/18] feat(textarea): 789012 - Add Textarea component

Add a native, unstyled textarea component that integrates with the Field system to provide automatic state handling and validation.

Enable content-aware auto-resizing via minRows/maxRows, support controlled and uncontrolled usage, and expose data attributes for styling based on control state. Add documentation, API reference, unit tests, and package export so the component is discoverable and consumable.
---
 docs/reference/generated/textarea.json        |  58 +++++
 .../react/components/textarea/page.mdx        |  43 ++++
 packages/react/package.json                   |   1 +
 packages/react/src/index.ts                   |   1 +
 packages/react/src/textarea/Textarea.test.tsx |  13 +
 packages/react/src/textarea/Textarea.tsx      | 228 ++++++++++++++++++
 .../src/textarea/TextareaDataAttributes.ts    |  30 +++
 packages/react/src/textarea/index.ts          |   1 +
 8 files changed, 375 insertions(+)
 create mode 100644 docs/reference/generated/textarea.json
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/page.mdx
 create mode 100644 packages/react/src/textarea/Textarea.test.tsx
 create mode 100644 packages/react/src/textarea/Textarea.tsx
 create mode 100644 packages/react/src/textarea/TextareaDataAttributes.ts
 create mode 100644 packages/react/src/textarea/index.ts

diff --git a/docs/reference/generated/textarea.json b/docs/reference/generated/textarea.json
new file mode 100644
index 0000000000..f8e8ebc7d2
--- /dev/null
+++ b/docs/reference/generated/textarea.json
@@ -0,0 +1,58 @@
+{
+  "name": "Textarea",
+  "description": "A native textarea element that automatically works with [Field](https://base-ui.com/react/components/field).\nRenders an `<textarea>` element.",
+  "props": {
+    "defaultValue": {
+      "type": "string | number | string[]",
+      "detailedType": "string | number | string[] | undefined"
+    },
+    "onValueChange": {
+      "type": "((value: string, eventDetails: Textarea.ChangeEventDetails) => void)",
+      "description": "Callback fired when the `value` changes. Use when controlled.",
+      "detailedType": "| ((\n    value: string,\n    eventDetails: Textarea.ChangeEventDetails,\n  ) => void)\n| undefined"
+    },
+    "maxRows": {
+      "type": "number",
+      "description": "Limit automatic height resizing to this many rows.",
+      "detailedType": "number | undefined"
+    },
+    "minRows": {
+      "type": "number",
+      "description": "Enable automatic height resizing by setting the minimum number of rows.\n\nPrefer the CSS property `field-sizing: content` when supported (not\nsupported in Safari and Firefox).",
+      "detailedType": "number | undefined"
+    },
+    "className": {
+      "type": "string | ((state: Field.Root.State) => string)",
+      "description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
+    },
+    "render": {
+      "type": "ReactElement | ((props: HTMLProps, state: Field.Root.State) => ReactElement)",
+      "description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render.",
+      "detailedType": "| ReactElement\n| ((\n    props: HTMLProps,\n    state: Field.Root.State,\n  ) => ReactElement)"
+    }
+  },
+  "dataAttributes": {
+    "data-disabled": {
+      "description": "Present when the textarea is disabled."
+    },
+    "data-valid": {
+      "description": "Present when the textarea is in valid state."
+    },
+    "data-invalid": {
+      "description": "Present when the textarea is in invalid state."
+    },
+    "data-dirty": {
+      "description": "Present when the textarea's value has changed."
+    },
+    "data-touched": {
+      "description": "Present when the textarea has been touched."
+    },
+    "data-filled": {
+      "description": "Present when the textarea is filled."
+    },
+    "data-focused": {
+      "description": "Present when the textarea is focused."
+    }
+  },
+  "cssVariables": {}
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/page.mdx b/docs/src/app/(public)/(content)/react/components/textarea/page.mdx
new file mode 100644
index 0000000000..94ab48dad0
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/page.mdx
@@ -0,0 +1,43 @@
+# Textarea
+
+<Subtitle>
+  A native textarea element that automatically works with [Field](/react/components/field).
+</Subtitle>
+
+<Meta name="description" content="A high-quality, unstyled React textarea component." />
+
+<Demo path="./demos/hero" />
+
+## Anatomy
+
+Import the component and use it as a single part:
+
+```jsx title="Anatomy"
+import { Textarea } from '@base-ui-components/react/textarea';
+
+<Textarea />;
+```
+
+## API reference
+
+<Reference component="Textarea" />
+
+## Examples
+
+### Infinite resize
+
+Setting only a `minRows` will make the textarea automatically resize to fit its content.
+
+<Demo path="./demos/infinite-resize" compact />
+
+### Max rows
+
+Setting both `minRows` and `maxRows` will make the textarea automatically resize between those limits.
+
+<Demo path="./demos/max-rows" compact />
+
+### Form integration
+
+The textarea works seamlessly with the [Form](/react/components/form) component and supports libraries like [Zod](https://zod.dev/) for schema validation.
+
+<Demo path="./demos/form" compact />
diff --git a/packages/react/package.json b/packages/react/package.json
index a92b910e3d..fe4ae0628a 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -58,6 +58,7 @@
     "./slider": "./src/slider/index.ts",
     "./switch": "./src/switch/index.ts",
     "./tabs": "./src/tabs/index.ts",
+    "./textarea": "./src/textarea/index.ts",
     "./toast": "./src/toast/index.ts",
     "./toggle": "./src/toggle/index.ts",
     "./toggle-group": "./src/toggle-group/index.ts",
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 93771c2091..55256bcab5 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -30,6 +30,7 @@ export * from './separator';
 export * from './slider';
 export * from './switch';
 export * from './tabs';
+export * from './textarea';
 export * from './toast';
 export * from './toggle';
 export * from './toggle-group';
diff --git a/packages/react/src/textarea/Textarea.test.tsx b/packages/react/src/textarea/Textarea.test.tsx
new file mode 100644
index 0000000000..4e2dcccd86
--- /dev/null
+++ b/packages/react/src/textarea/Textarea.test.tsx
@@ -0,0 +1,13 @@
+import * as React from 'react';
+import { Textarea } from '@base-ui-components/react/textarea';
+import { createRenderer } from '@mui/internal-test-utils';
+import { describeConformance } from '../../test/describeConformance';
+
+describe('<Textarea />', () => {
+  const { render } = createRenderer();
+
+  describeConformance(<Textarea />, () => ({
+    refInstanceof: window.HTMLTextAreaElement,
+    render,
+  }));
+});
diff --git a/packages/react/src/textarea/Textarea.tsx b/packages/react/src/textarea/Textarea.tsx
new file mode 100644
index 0000000000..fe5fded755
--- /dev/null
+++ b/packages/react/src/textarea/Textarea.tsx
@@ -0,0 +1,228 @@
+'use client';
+import * as React from 'react';
+import { useEventCallback } from '@base-ui-components/utils/useEventCallback';
+import { useControlled } from '@base-ui-components/utils/useControlled';
+import { useIsoLayoutEffect } from '@base-ui-components/utils/useIsoLayoutEffect';
+import { FieldRoot } from '../field/root/FieldRoot';
+import { useFieldRootContext } from '../field/root/FieldRootContext';
+import { fieldValidityMapping } from '../field/utils/constants';
+import { BaseUIComponentProps } from '../utils/types';
+import { useRenderElement } from '../utils/useRenderElement';
+import { useField } from '../field/useField';
+import { useBaseUiId } from '../utils/useBaseUiId';
+import { useFieldControlValidation } from '../field/control/useFieldControlValidation';
+import {
+  BaseUIChangeEventDetails,
+  createChangeEventDetails,
+} from '../utils/createBaseUIEventDetails';
+
+/**
+ * A native textarea element that automatically works with [Field](https://base-ui.com/react/components/field).
+ * Renders an `<textarea>` element.
+ *
+ * Documentation: [Base UI Textarea](https://base-ui.com/react/components/textarea)
+ */
+export const Textarea = React.forwardRef(function Textarea(
+  componentProps: Textarea.Props,
+  forwardedRef: React.ForwardedRef<HTMLTextAreaElement>,
+) {
+  const {
+    render,
+    className,
+    id: idProp,
+    name: nameProp,
+    value: valueProp,
+    disabled: disabledProp = false,
+    onValueChange,
+    defaultValue,
+    minRows,
+    maxRows,
+    style,
+    ...elementProps
+  } = componentProps;
+
+  const { state: fieldState, name: fieldName, disabled: fieldDisabled } = useFieldRootContext();
+
+  const disabled = fieldDisabled || disabledProp;
+  const name = fieldName ?? nameProp;
+
+  const state: Textarea.State = React.useMemo(
+    () => ({
+      ...fieldState,
+      disabled,
+    }),
+    [fieldState, disabled],
+  );
+
+  const {
+    setControlId,
+    labelId,
+    setTouched,
+    setDirty,
+    validityData,
+    setFocused,
+    setFilled,
+    validationMode,
+  } = useFieldRootContext();
+
+  const { getValidationProps, getInputValidationProps, commitValidation, inputRef } =
+    useFieldControlValidation();
+
+  const id = useBaseUiId(idProp);
+
+  useIsoLayoutEffect(() => {
+    setControlId(id);
+    return () => {
+      setControlId(undefined);
+    };
+  }, [id, setControlId]);
+
+  useIsoLayoutEffect(() => {
+    const hasExternalValue = valueProp != null;
+    if (inputRef.current?.value || (hasExternalValue && valueProp !== '')) {
+      setFilled(true);
+    } else if (hasExternalValue && valueProp === '') {
+      setFilled(false);
+    }
+  }, [inputRef, setFilled, valueProp]);
+
+  const [value, setValueUnwrapped] = useControlled({
+    controlled: valueProp,
+    default: defaultValue,
+    name: 'Textarea',
+    state: 'value',
+  });
+
+  const isControlled = valueProp !== undefined;
+
+  const setValue = useEventCallback(
+    (nextValue: string, eventDetails: Textarea.ChangeEventDetails) => {
+      onValueChange?.(nextValue, eventDetails);
+
+      if (eventDetails.isCanceled) {
+        return;
+      }
+
+      setValueUnwrapped(nextValue);
+    },
+  );
+
+  useField({
+    id,
+    name,
+    commitValidation,
+    value,
+    getValue: () => inputRef.current?.value,
+    controlRef: inputRef,
+  });
+
+  useIsoLayoutEffect(() => {
+    const el = inputRef.current;
+    if (!el || (minRows == null && maxRows == null)) {
+      return undefined;
+    }
+
+    const resize = () => {
+      el.style.height = 'auto';
+      const lineHeight = parseFloat(getComputedStyle(el).lineHeight) || 24;
+      const min = minRows != null ? minRows * lineHeight : 0;
+      const maxPx = maxRows != null ? maxRows * lineHeight : Infinity;
+      const target = Math.min(maxPx, Math.max(min, el.scrollHeight));
+      el.style.height = `${target}px`;
+      el.style.overflowY = el.scrollHeight > target ? 'auto' : 'hidden';
+    };
+
+    resize();
+    el.addEventListener('input', resize);
+    window.addEventListener('resize', resize);
+
+    return () => {
+      el.removeEventListener('input', resize);
+      window.removeEventListener('resize', resize);
+    };
+  }, [inputRef, minRows, maxRows]);
+
+  const element = useRenderElement('textarea', componentProps, {
+    ref: forwardedRef || undefined,
+    state,
+    props: [
+      {
+        id,
+        disabled,
+        name,
+        ref: inputRef,
+        ...(minRows != null ? { rows: minRows } : {}),
+        'aria-labelledby': labelId,
+        ...(minRows != null && !(style as any)?.height
+          ? {
+              style: {
+                ...(style as React.CSSProperties),
+                height: `${minRows * 24}px`,
+                resize: 'none',
+              },
+            }
+          : { style }),
+        ...(isControlled ? { value } : { defaultValue }),
+        onChange(event) {
+          const inputValue = event.currentTarget.value;
+          setValue(inputValue, createChangeEventDetails('none', event.nativeEvent));
+          setDirty(inputValue !== validityData.initialValue);
+          setFilled(inputValue !== '');
+        },
+        onFocus() {
+          setFocused(true);
+        },
+        onBlur(event: React.FocusEvent<HTMLTextAreaElement>) {
+          setTouched(true);
+          setFocused(false);
+
+          if (validationMode === 'onBlur') {
+            commitValidation(event.currentTarget.value);
+          }
+        },
+        onKeyDown(event) {
+          if (
+            event.currentTarget.tagName === 'TEXTAREA' &&
+            event.key === 'Enter' &&
+            event.shiftKey === true
+          ) {
+            setTouched(true);
+            commitValidation(event.currentTarget.value);
+          }
+        },
+      },
+      getValidationProps(),
+      getInputValidationProps(),
+      elementProps,
+    ],
+    stateAttributesMapping: fieldValidityMapping,
+  });
+
+  return element;
+});
+
+export namespace Textarea {
+  export type State = FieldRoot.State;
+
+  export interface Props extends BaseUIComponentProps<'textarea', State> {
+    /**
+     * Enable automatic height resizing by setting the minimum number of rows.
+     *
+     * Prefer the CSS property `field-sizing: content` when supported (not
+     * supported in Safari and Firefox).
+     */
+    minRows?: number;
+    /**
+     * Limit automatic height resizing to this many rows.
+     */
+    maxRows?: number;
+    /**
+     * Callback fired when the `value` changes. Use when controlled.
+     */
+    onValueChange?: (value: string, eventDetails: ChangeEventDetails) => void;
+    defaultValue?: React.ComponentProps<'textarea'>['defaultValue'];
+  }
+
+  export type ChangeEventReason = 'none';
+  export type ChangeEventDetails = BaseUIChangeEventDetails<ChangeEventReason>;
+}
diff --git a/packages/react/src/textarea/TextareaDataAttributes.ts b/packages/react/src/textarea/TextareaDataAttributes.ts
new file mode 100644
index 0000000000..2fc3190555
--- /dev/null
+++ b/packages/react/src/textarea/TextareaDataAttributes.ts
@@ -0,0 +1,30 @@
+export enum TextareaDataAttributes {
+  /**
+   * Present when the textarea is disabled.
+   */
+  disabled = 'data-disabled',
+  /**
+   * Present when the textarea is in valid state.
+   */
+  valid = 'data-valid',
+  /**
+   * Present when the textarea is in invalid state.
+   */
+  invalid = 'data-invalid',
+  /**
+   * Present when the textarea has been touched.
+   */
+  touched = 'data-touched',
+  /**
+   * Present when the textarea's value has changed.
+   */
+  dirty = 'data-dirty',
+  /**
+   * Present when the textarea is filled.
+   */
+  filled = 'data-filled',
+  /**
+   * Present when the textarea is focused.
+   */
+  focused = 'data-focused',
+}
diff --git a/packages/react/src/textarea/index.ts b/packages/react/src/textarea/index.ts
new file mode 100644
index 0000000000..f4212c043e
--- /dev/null
+++ b/packages/react/src/textarea/index.ts
@@ -0,0 +1 @@
+export { Textarea } from './Textarea';

From 1ec8837b3c44fdd9ad77b601305167104a15362a Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Thu, 2 Oct 2025 21:25:46 -0500
Subject: [PATCH 02/18] add demos

---
 .../form/demos/zod/tailwind/index.tsx         | 11 +++
 .../demos/form/css-modules/index.module.css   | 93 +++++++++++++++++++
 .../textarea/demos/form/css-modules/index.tsx | 58 ++++++++++++
 .../components/textarea/demos/form/index.ts   |  3 +
 .../textarea/demos/form/tailwind/index.tsx    | 64 +++++++++++++
 .../demos/hero/css-modules/index.module.css   | 24 +++++
 .../textarea/demos/hero/css-modules/index.tsx |  7 ++
 .../components/textarea/demos/hero/index.ts   |  3 +
 .../textarea/demos/hero/tailwind/index.tsx    | 11 +++
 .../css-modules/index.module.css              | 24 +++++
 .../infinite-resize/css-modules/index.tsx     |  7 ++
 .../textarea/demos/infinite-resize/index.ts   |  3 +
 .../demos/infinite-resize/tailwind/index.tsx  | 12 +++
 .../max-rows/css-modules/index.module.css     | 24 +++++
 .../demos/max-rows/css-modules/index.tsx      |  9 ++
 .../textarea/demos/max-rows/index.ts          |  3 +
 .../demos/max-rows/tailwind/index.tsx         | 13 +++
 docs/src/nav.ts                               |  5 +
 18 files changed, 374 insertions(+)
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.tsx
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/form/index.ts
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.tsx
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/hero/index.ts
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.tsx
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/index.ts
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.tsx
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/index.ts
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx

diff --git a/docs/src/app/(public)/(content)/react/components/form/demos/zod/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/form/demos/zod/tailwind/index.tsx
index 280743ed3c..cdb31c27bb 100644
--- a/docs/src/app/(public)/(content)/react/components/form/demos/zod/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/form/demos/zod/tailwind/index.tsx
@@ -2,10 +2,12 @@ import * as React from 'react';
 import { z } from 'zod';
 import { Field } from '@base-ui-components/react/field';
 import { Form } from '@base-ui-components/react/form';
+import { Textarea } from '@base-ui-components/react/textarea';
 
 const schema = z.object({
   name: z.string().min(1, 'Name is required'),
   age: z.coerce.number('Age must be a number').positive('Age must be a positive number'),
+  notes: z.string().optional(),
 });
 
 async function submitForm(event: React.FormEvent<HTMLFormElement>) {
@@ -54,6 +56,15 @@ export default function Page() {
         />
         <Field.Error className="text-sm text-red-800" />
       </Field.Root>
+
+      <Field.Root name="notes" className="flex flex-col items-start gap-1">
+        <Field.Label className="text-sm font-medium text-gray-900">Notes</Field.Label>
+        <Textarea
+          placeholder="Enter notes"
+          className="w-full rounded-md border border-gray-200 px-3.5 py-2 text-base text-gray-900 focus:outline focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
+        />
+        <Field.Error className="text-sm text-red-800" />
+      </Field.Root>
       <button
         type="submit"
         className="flex h-10 items-center justify-center rounded-md border border-gray-200 bg-gray-50 px-3.5 text-base font-medium text-gray-900 select-none hover:bg-gray-100 focus-visible:outline focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-blue-800 active:bg-gray-100 disabled:cursor-not-allowed disabled:bg-gray-100 disabled:text-gray-400"
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css
new file mode 100644
index 0000000000..fba091d168
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css
@@ -0,0 +1,93 @@
+.Form {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  width: 100%;
+  max-width: 16rem;
+}
+
+.Field {
+  display: flex;
+  flex-direction: column;
+  align-items: start;
+  gap: 0.25rem;
+}
+
+.Label {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 500;
+  color: var(--color-gray-900);
+}
+
+.Textarea {
+  box-sizing: border-box;
+  margin: 0;
+  border: 1px solid var(--color-gray-200);
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  max-width: 16rem;
+  min-height: 4rem;
+  border-radius: 0.375rem;
+  font-family: inherit;
+  font-size: 1rem;
+  line-height: 1.5rem;
+  letter-spacing: 0em;
+  font-weight: normal;
+  background-color: transparent;
+  color: var(--color-gray-900);
+  field-sizing: content;
+  resize: vertical;
+
+  &:focus {
+    outline: 2px solid var(--color-blue);
+    outline-offset: -1px;
+  }
+}
+
+.Error {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  color: var(--color-red-800);
+}
+
+.Button {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 2.5rem;
+  padding: 0 0.875rem;
+  margin: 0;
+  outline: 0;
+  border: 1px solid var(--color-gray-200);
+  border-radius: 0.375rem;
+  background-color: var(--color-gray-50);
+  font-family: inherit;
+  font-size: 1rem;
+  font-weight: 500;
+  line-height: 1.5rem;
+  color: var(--color-gray-900);
+  user-select: none;
+
+  @media (hover: hover) {
+    &:hover {
+      background-color: var(--color-gray-100);
+    }
+  }
+
+  &:active {
+    background-color: var(--color-gray-100);
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    color: var(--color-gray-400);
+    background-color: var(--color-gray-100);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--color-blue);
+    outline-offset: -1px;
+  }
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.tsx
new file mode 100644
index 0000000000..9d262f78de
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.tsx
@@ -0,0 +1,58 @@
+import * as React from 'react';
+import { Field } from '@base-ui-components/react/field';
+import { Form } from '@base-ui-components/react/form';
+import { Textarea } from '@base-ui-components/react/textarea';
+import styles from './index.module.css';
+
+export default function ExampleForm() {
+  const [errors, setErrors] = React.useState({});
+  const [loading, setLoading] = React.useState(false);
+
+  return (
+    <Form
+      className={styles.Form}
+      errors={errors}
+      onClearErrors={setErrors}
+      onSubmit={async (event) => {
+        event.preventDefault();
+        const formData = new FormData(event.currentTarget);
+        const value = formData.get('feedback') as string;
+
+        setLoading(true);
+        const response = await submitForm(value);
+        const serverErrors = {
+          feedback: response.error,
+        };
+
+        setErrors(serverErrors);
+        setLoading(false);
+      }}
+    >
+      <Field.Root name="feedback" className={styles.Field}>
+        <Field.Label className={styles.Label}>Feedback</Field.Label>
+        <Textarea placeholder="Enter your feedback" className={styles.Textarea} />
+        <Field.Error className={styles.Error} />
+      </Field.Root>
+      <button disabled={loading} type="submit" className={styles.Button}>
+        Submit
+      </button>
+    </Form>
+  );
+}
+
+async function submitForm(value: string) {
+  // Mimic a server response
+  await new Promise((resolve) => {
+    setTimeout(resolve, 1000);
+  });
+
+  try {
+    if (value.length < 10) {
+      return { error: 'Feedback must be at least 10 characters long' };
+    }
+  } catch {
+    return { error: 'Invalid feedback' };
+  }
+
+  return { success: true };
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/index.ts b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/index.ts
new file mode 100644
index 0000000000..80097d6015
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/index.ts
@@ -0,0 +1,3 @@
+'use client';
+export { default as CssModules } from './css-modules';
+export { default as Tailwind } from './tailwind';
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx
new file mode 100644
index 0000000000..41c72ee687
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx
@@ -0,0 +1,64 @@
+import * as React from 'react';
+import { Field } from '@base-ui-components/react/field';
+import { Form } from '@base-ui-components/react/form';
+import { Textarea } from '@base-ui-components/react/textarea';
+
+export default function ExampleForm() {
+  const [errors, setErrors] = React.useState({});
+  const [loading, setLoading] = React.useState(false);
+
+  return (
+    <Form
+      className="flex w-full max-w-64 flex-col gap-4"
+      errors={errors}
+      onClearErrors={setErrors}
+      onSubmit={async (event) => {
+        event.preventDefault();
+        const formData = new FormData(event.currentTarget);
+        const value = formData.get('feedback') as string;
+
+        setLoading(true);
+        const response = await submitForm(value);
+        const serverErrors = {
+          feedback: response.error,
+        };
+
+        setErrors(serverErrors);
+        setLoading(false);
+      }}
+    >
+      <Field.Root name="feedback" className="flex flex-col items-start gap-1">
+        <Field.Label className="text-sm font-medium text-gray-900">Feedback</Field.Label>
+        <Textarea
+          placeholder="Enter your feedback"
+          className="w-full max-w-64 min-h-16 rounded-md border border-gray-200 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800 px-3 py-2 field-sizing-content resize-y"
+        />
+        <Field.Error className="text-sm text-red-800" />
+      </Field.Root>
+      <button
+        disabled={loading}
+        type="submit"
+        className="flex h-10 items-center justify-center rounded-md border border-gray-200 bg-gray-50 px-3.5 text-base font-medium text-gray-900 select-none hover:bg-gray-100 focus-visible:outline focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-blue-800 active:bg-gray-100 disabled:cursor-not-allowed disabled:bg-gray-100 disabled:text-gray-400"
+      >
+        Submit
+      </button>
+    </Form>
+  );
+}
+
+async function submitForm(value: string) {
+  // Mimic a server response
+  await new Promise((resolve) => {
+    setTimeout(resolve, 1000);
+  });
+
+  try {
+    if (value.length < 10) {
+      return { error: 'Feedback must be at least 10 characters long' };
+    }
+  } catch {
+    return { error: 'Invalid feedback' };
+  }
+
+  return { success: true };
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css
new file mode 100644
index 0000000000..5dfd8ecea2
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css
@@ -0,0 +1,24 @@
+.Textarea {
+  box-sizing: border-box;
+  margin: 0;
+  border: 1px solid var(--color-gray-200);
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  max-width: 16rem;
+  min-height: 4rem;
+  border-radius: 0.375rem;
+  font-family: inherit;
+  font-size: 1rem;
+  line-height: 1.5rem;
+  letter-spacing: 0em;
+  font-weight: normal;
+  background-color: transparent;
+  color: var(--color-gray-900);
+  field-sizing: content;
+  resize: vertical;
+
+  &:focus {
+    outline: 2px solid var(--color-blue);
+    outline-offset: -1px;
+  }
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.tsx
new file mode 100644
index 0000000000..8ff81679f9
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.tsx
@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { Textarea } from '@base-ui-components/react/textarea';
+import styles from './index.module.css';
+
+export default function ExampleTextarea() {
+  return <Textarea placeholder="Type something…" className={styles.Textarea} />;
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/index.ts b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/index.ts
new file mode 100644
index 0000000000..80097d6015
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/index.ts
@@ -0,0 +1,3 @@
+'use client';
+export { default as CssModules } from './css-modules';
+export { default as Tailwind } from './tailwind';
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx
new file mode 100644
index 0000000000..e54cacedc5
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx
@@ -0,0 +1,11 @@
+import * as React from 'react';
+import { Textarea } from '@base-ui-components/react/textarea';
+
+export default function ExampleTextarea() {
+  return (
+    <Textarea
+      placeholder="Type something…"
+      className="w-full max-w-64 min-h-16 rounded-md border border-gray-200 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800 px-3 py-2 field-sizing-content resize-y"
+    />
+  );
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
new file mode 100644
index 0000000000..5dfd8ecea2
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
@@ -0,0 +1,24 @@
+.Textarea {
+  box-sizing: border-box;
+  margin: 0;
+  border: 1px solid var(--color-gray-200);
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  max-width: 16rem;
+  min-height: 4rem;
+  border-radius: 0.375rem;
+  font-family: inherit;
+  font-size: 1rem;
+  line-height: 1.5rem;
+  letter-spacing: 0em;
+  font-weight: normal;
+  background-color: transparent;
+  color: var(--color-gray-900);
+  field-sizing: content;
+  resize: vertical;
+
+  &:focus {
+    outline: 2px solid var(--color-blue);
+    outline-offset: -1px;
+  }
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.tsx
new file mode 100644
index 0000000000..6cccf7391e
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.tsx
@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { Textarea } from '@base-ui-components/react/textarea';
+import styles from './index.module.css';
+
+export default function ExampleTextarea() {
+  return <Textarea placeholder="Type something…" minRows={4} className={styles.Textarea} />;
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/index.ts b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/index.ts
new file mode 100644
index 0000000000..80097d6015
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/index.ts
@@ -0,0 +1,3 @@
+'use client';
+export { default as CssModules } from './css-modules';
+export { default as Tailwind } from './tailwind';
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
new file mode 100644
index 0000000000..6dcc2305a5
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
@@ -0,0 +1,12 @@
+import * as React from 'react';
+import { Textarea } from '@base-ui-components/react/textarea';
+
+export default function ExampleTextarea() {
+  return (
+    <Textarea
+      placeholder="Type something…"
+      minRows={4}
+      className="w-full max-w-64 min-h-16 rounded-md border border-gray-200 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800 px-3 py-2 field-sizing-content resize-y"
+    />
+  );
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
new file mode 100644
index 0000000000..5dfd8ecea2
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
@@ -0,0 +1,24 @@
+.Textarea {
+  box-sizing: border-box;
+  margin: 0;
+  border: 1px solid var(--color-gray-200);
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  max-width: 16rem;
+  min-height: 4rem;
+  border-radius: 0.375rem;
+  font-family: inherit;
+  font-size: 1rem;
+  line-height: 1.5rem;
+  letter-spacing: 0em;
+  font-weight: normal;
+  background-color: transparent;
+  color: var(--color-gray-900);
+  field-sizing: content;
+  resize: vertical;
+
+  &:focus {
+    outline: 2px solid var(--color-blue);
+    outline-offset: -1px;
+  }
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.tsx
new file mode 100644
index 0000000000..cb0075261d
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.tsx
@@ -0,0 +1,9 @@
+import * as React from 'react';
+import { Textarea } from '@base-ui-components/react/textarea';
+import styles from './index.module.css';
+
+export default function ExampleTextarea() {
+  return (
+    <Textarea placeholder="Type something…" minRows={4} maxRows={8} className={styles.Textarea} />
+  );
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/index.ts b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/index.ts
new file mode 100644
index 0000000000..80097d6015
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/index.ts
@@ -0,0 +1,3 @@
+'use client';
+export { default as CssModules } from './css-modules';
+export { default as Tailwind } from './tailwind';
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx
new file mode 100644
index 0000000000..ffd0670bdb
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx
@@ -0,0 +1,13 @@
+import * as React from 'react';
+import { Textarea } from '@base-ui-components/react/textarea';
+
+export default function ExampleTextarea() {
+  return (
+    <Textarea
+      placeholder="Type something…"
+      minRows={4}
+      maxRows={8}
+      className="w-full max-w-64 min-h-16 rounded-md border border-gray-200 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800 px-3 py-2 field-sizing-content resize-y"
+    />
+  );
+}
diff --git a/docs/src/nav.ts b/docs/src/nav.ts
index 13b2cf2222..23d2991d7b 100644
--- a/docs/src/nav.ts
+++ b/docs/src/nav.ts
@@ -183,6 +183,11 @@ export const nav: NavGroup[] = [
         label: 'Tabs',
         href: '/react/components/tabs',
       },
+      {
+        label: 'Textarea',
+        href: '/react/components/textarea',
+        isNew: true,
+      },
       {
         label: 'Toast',
         href: '/react/components/toast',

From 2d083619ea521093b71ffcf711ded08e7211f630 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Thu, 2 Oct 2025 21:37:04 -0500
Subject: [PATCH 03/18] revert form demo change

---
 .../components/form/demos/zod/tailwind/index.tsx      | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/docs/src/app/(public)/(content)/react/components/form/demos/zod/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/form/demos/zod/tailwind/index.tsx
index cdb31c27bb..280743ed3c 100644
--- a/docs/src/app/(public)/(content)/react/components/form/demos/zod/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/form/demos/zod/tailwind/index.tsx
@@ -2,12 +2,10 @@ import * as React from 'react';
 import { z } from 'zod';
 import { Field } from '@base-ui-components/react/field';
 import { Form } from '@base-ui-components/react/form';
-import { Textarea } from '@base-ui-components/react/textarea';
 
 const schema = z.object({
   name: z.string().min(1, 'Name is required'),
   age: z.coerce.number('Age must be a number').positive('Age must be a positive number'),
-  notes: z.string().optional(),
 });
 
 async function submitForm(event: React.FormEvent<HTMLFormElement>) {
@@ -56,15 +54,6 @@ export default function Page() {
         />
         <Field.Error className="text-sm text-red-800" />
       </Field.Root>
-
-      <Field.Root name="notes" className="flex flex-col items-start gap-1">
-        <Field.Label className="text-sm font-medium text-gray-900">Notes</Field.Label>
-        <Textarea
-          placeholder="Enter notes"
-          className="w-full rounded-md border border-gray-200 px-3.5 py-2 text-base text-gray-900 focus:outline focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
-        />
-        <Field.Error className="text-sm text-red-800" />
-      </Field.Root>
       <button
         type="submit"
         className="flex h-10 items-center justify-center rounded-md border border-gray-200 bg-gray-50 px-3.5 text-base font-medium text-gray-900 select-none hover:bg-gray-100 focus-visible:outline focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-blue-800 active:bg-gray-100 disabled:cursor-not-allowed disabled:bg-gray-100 disabled:text-gray-400"

From c2b25c6177308041468bbb4f48d1756bf2ced528 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Thu, 2 Oct 2025 21:43:48 -0500
Subject: [PATCH 04/18] prettier

---
 .../react/components/textarea/demos/form/tailwind/index.tsx     | 2 +-
 .../react/components/textarea/demos/hero/tailwind/index.tsx     | 2 +-
 .../textarea/demos/infinite-resize/tailwind/index.tsx           | 2 +-
 .../react/components/textarea/demos/max-rows/tailwind/index.tsx | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx
index 41c72ee687..04b0d5dd1f 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx
@@ -31,7 +31,7 @@ export default function ExampleForm() {
         <Field.Label className="text-sm font-medium text-gray-900">Feedback</Field.Label>
         <Textarea
           placeholder="Enter your feedback"
-          className="w-full max-w-64 min-h-16 rounded-md border border-gray-200 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800 px-3 py-2 field-sizing-content resize-y"
+          className="field-sizing-content min-h-16 w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
         />
         <Field.Error className="text-sm text-red-800" />
       </Field.Root>
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx
index e54cacedc5..f207974f04 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx
@@ -5,7 +5,7 @@ export default function ExampleTextarea() {
   return (
     <Textarea
       placeholder="Type something…"
-      className="w-full max-w-64 min-h-16 rounded-md border border-gray-200 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800 px-3 py-2 field-sizing-content resize-y"
+      className="field-sizing-content min-h-16 w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
     />
   );
 }
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
index 6dcc2305a5..7e1a8aa8b6 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
@@ -6,7 +6,7 @@ export default function ExampleTextarea() {
     <Textarea
       placeholder="Type something…"
       minRows={4}
-      className="w-full max-w-64 min-h-16 rounded-md border border-gray-200 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800 px-3 py-2 field-sizing-content resize-y"
+      className="field-sizing-content min-h-16 w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
     />
   );
 }
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx
index ffd0670bdb..439d842e77 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx
@@ -7,7 +7,7 @@ export default function ExampleTextarea() {
       placeholder="Type something…"
       minRows={4}
       maxRows={8}
-      className="w-full max-w-64 min-h-16 rounded-md border border-gray-200 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800 px-3 py-2 field-sizing-content resize-y"
+      className="field-sizing-content min-h-16 w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
     />
   );
 }

From 671258bb133ddcd82160368af43cbfb85747dbb3 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Thu, 2 Oct 2025 21:48:51 -0500
Subject: [PATCH 05/18] dedupe

---
 pnpm-lock.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6bff1230dd..951177d055 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -12435,7 +12435,7 @@ snapshots:
       eslint-config-prettier: 10.1.8(eslint@9.36.0(jiti@2.5.1))
       eslint-import-resolver-typescript: 4.4.4(eslint-plugin-import@2.32.0(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1))
       eslint-module-utils: 2.12.1(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@4.4.4(eslint-plugin-import@2.32.0(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@4.4.4(eslint-plugin-import@2.32.0(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@4.4.4)(eslint@9.36.0(jiti@2.5.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.36.0(jiti@2.5.1))
       eslint-plugin-mocha: 11.1.0(eslint@9.36.0(jiti@2.5.1))
       eslint-plugin-react: 7.37.5(eslint@9.36.0(jiti@2.5.1))
@@ -16669,7 +16669,7 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@4.4.4(eslint-plugin-import@2.32.0(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@4.4.4)(eslint@9.36.0(jiti@2.5.1))
     transitivePeerDependencies:
       - supports-color
 
@@ -16683,7 +16683,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@4.4.4(eslint-plugin-import@2.32.0(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1)):
+  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@4.4.4)(eslint@9.36.0(jiti@2.5.1)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9

From 42d30cfecd8a0943410c4b0c884b72c92a2caeb5 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Thu, 2 Oct 2025 22:09:13 -0500
Subject: [PATCH 06/18] stylelint

---
 .../components/textarea/demos/form/css-modules/index.module.css  | 1 -
 .../components/textarea/demos/hero/css-modules/index.module.css  | 1 -
 .../textarea/demos/infinite-resize/css-modules/index.module.css  | 1 -
 .../textarea/demos/max-rows/css-modules/index.module.css         | 1 -
 4 files changed, 4 deletions(-)

diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css
index fba091d168..738fb609bc 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css
@@ -32,7 +32,6 @@
   font-family: inherit;
   font-size: 1rem;
   line-height: 1.5rem;
-  letter-spacing: 0em;
   font-weight: normal;
   background-color: transparent;
   color: var(--color-gray-900);
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css
index 5dfd8ecea2..b1a59e8c89 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css
@@ -10,7 +10,6 @@
   font-family: inherit;
   font-size: 1rem;
   line-height: 1.5rem;
-  letter-spacing: 0em;
   font-weight: normal;
   background-color: transparent;
   color: var(--color-gray-900);
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
index 5dfd8ecea2..b1a59e8c89 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
@@ -10,7 +10,6 @@
   font-family: inherit;
   font-size: 1rem;
   line-height: 1.5rem;
-  letter-spacing: 0em;
   font-weight: normal;
   background-color: transparent;
   color: var(--color-gray-900);
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
index 5dfd8ecea2..b1a59e8c89 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
@@ -10,7 +10,6 @@
   font-family: inherit;
   font-size: 1rem;
   line-height: 1.5rem;
-  letter-spacing: 0em;
   font-weight: normal;
   background-color: transparent;
   color: var(--color-gray-900);

From 5389067ccab5038770befb3c3136adc9722257cc Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Fri, 3 Oct 2025 11:08:01 -0500
Subject: [PATCH 07/18] Remove field-sizing from examples

Removes usage of the experimental field-sizing property and related Tailwind utility from textarea examples and removes hardcoded min-height in CSS modules.

Avoids depending on a feature with limited browser support (~71.47%). Adds space to create a dedicated example and documentation with compatibility research once support reaches ~90%, keeping demos stable and predictable in the meantime.
---
 .../components/textarea/demos/form/css-modules/index.module.css | 2 --
 .../react/components/textarea/demos/form/tailwind/index.tsx     | 2 +-
 .../components/textarea/demos/hero/css-modules/index.module.css | 2 --
 .../react/components/textarea/demos/hero/tailwind/index.tsx     | 2 +-
 .../textarea/demos/infinite-resize/css-modules/index.module.css | 2 --
 .../textarea/demos/infinite-resize/tailwind/index.tsx           | 2 +-
 .../textarea/demos/max-rows/css-modules/index.module.css        | 2 --
 .../react/components/textarea/demos/max-rows/tailwind/index.tsx | 2 +-
 8 files changed, 4 insertions(+), 12 deletions(-)

diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css
index 738fb609bc..f27c41c55f 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/css-modules/index.module.css
@@ -27,7 +27,6 @@
   width: 100%;
   padding: 0.5rem 0.75rem;
   max-width: 16rem;
-  min-height: 4rem;
   border-radius: 0.375rem;
   font-family: inherit;
   font-size: 1rem;
@@ -35,7 +34,6 @@
   font-weight: normal;
   background-color: transparent;
   color: var(--color-gray-900);
-  field-sizing: content;
   resize: vertical;
 
   &:focus {
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx
index 04b0d5dd1f..0c922517c7 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/form/tailwind/index.tsx
@@ -31,7 +31,7 @@ export default function ExampleForm() {
         <Field.Label className="text-sm font-medium text-gray-900">Feedback</Field.Label>
         <Textarea
           placeholder="Enter your feedback"
-          className="field-sizing-content min-h-16 w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
+          className="w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
         />
         <Field.Error className="text-sm text-red-800" />
       </Field.Root>
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css
index b1a59e8c89..96bc6cfbe5 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/css-modules/index.module.css
@@ -5,7 +5,6 @@
   width: 100%;
   padding: 0.5rem 0.75rem;
   max-width: 16rem;
-  min-height: 4rem;
   border-radius: 0.375rem;
   font-family: inherit;
   font-size: 1rem;
@@ -13,7 +12,6 @@
   font-weight: normal;
   background-color: transparent;
   color: var(--color-gray-900);
-  field-sizing: content;
   resize: vertical;
 
   &:focus {
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx
index f207974f04..a8ee4e078f 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/hero/tailwind/index.tsx
@@ -5,7 +5,7 @@ export default function ExampleTextarea() {
   return (
     <Textarea
       placeholder="Type something…"
-      className="field-sizing-content min-h-16 w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
+      className="w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
     />
   );
 }
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
index b1a59e8c89..96bc6cfbe5 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
@@ -5,7 +5,6 @@
   width: 100%;
   padding: 0.5rem 0.75rem;
   max-width: 16rem;
-  min-height: 4rem;
   border-radius: 0.375rem;
   font-family: inherit;
   font-size: 1rem;
@@ -13,7 +12,6 @@
   font-weight: normal;
   background-color: transparent;
   color: var(--color-gray-900);
-  field-sizing: content;
   resize: vertical;
 
   &:focus {
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
index 7e1a8aa8b6..d038ab6c78 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
@@ -6,7 +6,7 @@ export default function ExampleTextarea() {
     <Textarea
       placeholder="Type something…"
       minRows={4}
-      className="field-sizing-content min-h-16 w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
+      className="w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
     />
   );
 }
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
index b1a59e8c89..96bc6cfbe5 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
@@ -5,7 +5,6 @@
   width: 100%;
   padding: 0.5rem 0.75rem;
   max-width: 16rem;
-  min-height: 4rem;
   border-radius: 0.375rem;
   font-family: inherit;
   font-size: 1rem;
@@ -13,7 +12,6 @@
   font-weight: normal;
   background-color: transparent;
   color: var(--color-gray-900);
-  field-sizing: content;
   resize: vertical;
 
   &:focus {
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx
index 439d842e77..fcf259abe8 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx
@@ -7,7 +7,7 @@ export default function ExampleTextarea() {
       placeholder="Type something…"
       minRows={4}
       maxRows={8}
-      className="field-sizing-content min-h-16 w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
+      className="w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
     />
   );
 }

From 863b1c9c8c02cbc0ac65651abb8b4f3a9d6ae788 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Fri, 3 Oct 2025 11:08:14 -0500
Subject: [PATCH 08/18] update docs

---
 docs/reference/generated/textarea.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/reference/generated/textarea.json b/docs/reference/generated/textarea.json
index f8e8ebc7d2..89a65b6b39 100644
--- a/docs/reference/generated/textarea.json
+++ b/docs/reference/generated/textarea.json
@@ -18,7 +18,7 @@
     },
     "minRows": {
       "type": "number",
-      "description": "Enable automatic height resizing by setting the minimum number of rows.\n\nPrefer the CSS property `field-sizing: content` when supported (not\nsupported in Safari and Firefox).",
+      "description": "Enable automatic height resizing by setting the minimum number of rows.",
       "detailedType": "number | undefined"
     },
     "className": {

From 597384c9a16f9e8f37bddf911429fb87f2f26e62 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Fri, 3 Oct 2025 12:22:33 -0500
Subject: [PATCH 09/18] Remove 'compact' attribute from demo components in
 textarea documentation

---
 .../(public)/(content)/react/components/textarea/page.mdx   | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/src/app/(public)/(content)/react/components/textarea/page.mdx b/docs/src/app/(public)/(content)/react/components/textarea/page.mdx
index 94ab48dad0..ad3f0ea256 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/page.mdx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/page.mdx
@@ -28,16 +28,16 @@ import { Textarea } from '@base-ui-components/react/textarea';
 
 Setting only a `minRows` will make the textarea automatically resize to fit its content.
 
-<Demo path="./demos/infinite-resize" compact />
+<Demo path="./demos/infinite-resize" />
 
 ### Max rows
 
 Setting both `minRows` and `maxRows` will make the textarea automatically resize between those limits.
 
-<Demo path="./demos/max-rows" compact />
+<Demo path="./demos/max-rows" />
 
 ### Form integration
 
 The textarea works seamlessly with the [Form](/react/components/form) component and supports libraries like [Zod](https://zod.dev/) for schema validation.
 
-<Demo path="./demos/form" compact />
+<Demo path="./demos/form" />

From a6eae6a0d8376545cc18721c08567454d6ce4189 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Fri, 3 Oct 2025 12:22:40 -0500
Subject: [PATCH 10/18] Enhance Textarea component with automatic height
 resizing and hidden textarea for improved performance

---
 packages/react/src/textarea/Textarea.tsx | 214 +++++++++++++++++++++--
 1 file changed, 199 insertions(+), 15 deletions(-)

diff --git a/packages/react/src/textarea/Textarea.tsx b/packages/react/src/textarea/Textarea.tsx
index fe5fded755..c375f9b1cb 100644
--- a/packages/react/src/textarea/Textarea.tsx
+++ b/packages/react/src/textarea/Textarea.tsx
@@ -41,6 +41,8 @@ export const Textarea = React.forwardRef(function Textarea(
     ...elementProps
   } = componentProps;
 
+  const placeholder = (elementProps as any)?.placeholder as string | undefined;
+
   const { state: fieldState, name: fieldName, disabled: fieldDisabled } = useFieldRootContext();
 
   const disabled = fieldDisabled || disabledProp;
@@ -68,6 +70,9 @@ export const Textarea = React.forwardRef(function Textarea(
   const { getValidationProps, getInputValidationProps, commitValidation, inputRef } =
     useFieldControlValidation();
 
+  const hiddenTextareaRef = React.useRef<HTMLTextAreaElement>(null);
+  const heightRef = React.useRef<number | null>(null);
+
   const id = useBaseUiId(idProp);
 
   useIsoLayoutEffect(() => {
@@ -118,29 +123,189 @@ export const Textarea = React.forwardRef(function Textarea(
 
   useIsoLayoutEffect(() => {
     const el = inputRef.current;
-    if (!el || (minRows == null && maxRows == null)) {
+    const hidden = hiddenTextareaRef.current;
+
+    if (!el || !hidden || (minRows == null && maxRows == null)) {
       return undefined;
     }
 
+    const getStyleValue = (str: string) => parseInt(str, 10) || 0;
+
+    const calculate = () => {
+      const computedStyle = getComputedStyle(el);
+
+      let width = computedStyle.width;
+      if (!width || width === '0px') {
+        const rect = el.getBoundingClientRect();
+        width = rect.width ? `${rect.width}px` : width;
+      }
+
+      if (!width || width === '0px') {
+        return null;
+      }
+
+      const styleToCopy = [
+        'boxSizing',
+        'width',
+        'paddingTop',
+        'paddingBottom',
+        'paddingLeft',
+        'paddingRight',
+        'borderTopWidth',
+        'borderBottomWidth',
+        'fontFamily',
+        'fontSize',
+        'fontWeight',
+        'fontStyle',
+        'letterSpacing',
+        'textTransform',
+        'textIndent',
+        'lineHeight',
+        'whiteSpace',
+      ];
+
+      hidden.style.width = width;
+      for (const propName of styleToCopy) {
+        hidden.style[propName as keyof Omit<CSSStyleDeclaration, 'length' | 'parentRule'>] = (computedStyle as any)[propName];
+      }
+
+      hidden.style.whiteSpace =
+        computedStyle.whiteSpace === 'pre-wrap' || computedStyle.whiteSpace === 'pre-line'
+          ? computedStyle.whiteSpace
+          : 'pre-wrap';
+
+      hidden.value = el.value || placeholder || 'x';
+      if (hidden.value.slice(-1) === '\n') {
+        hidden.value += ' ';
+      }
+
+      const boxSizing = computedStyle.boxSizing;
+      const paddingTop = getStyleValue(computedStyle.paddingTop);
+      const paddingBottom = getStyleValue(computedStyle.paddingBottom);
+      const padding = paddingTop + paddingBottom;
+      const border =
+        getStyleValue(computedStyle.borderBottomWidth) +
+        getStyleValue(computedStyle.borderTopWidth);
+
+      const innerScrollHeight = hidden.scrollHeight;
+
+      hidden.value = 'x';
+      const singleRowScrollHeight = hidden.scrollHeight || 1;
+      const singleRowContentHeight = Math.max(singleRowScrollHeight - padding, 1);
+
+      const currentContentHeight = Math.max(innerScrollHeight - padding, 0);
+
+      let desiredContentHeight = currentContentHeight;
+      if (minRows) {
+        desiredContentHeight = Math.max(
+          Number(minRows) * singleRowContentHeight,
+          desiredContentHeight,
+        );
+      }
+      if (maxRows) {
+        desiredContentHeight = Math.min(
+          Number(maxRows) * singleRowContentHeight,
+          desiredContentHeight,
+        );
+      }
+      desiredContentHeight = Math.max(desiredContentHeight, singleRowContentHeight);
+
+      const outerHeightStyle =
+        boxSizing === 'border-box' ? desiredContentHeight + padding + border : desiredContentHeight;
+
+      const isOverflowing = currentContentHeight > desiredContentHeight + 1;
+
+      const rowsOccupied = currentContentHeight / singleRowContentHeight;
+
+      return {
+        outerHeightStyle,
+        isOverflowing,
+        rowsOccupied,
+      } as { outerHeightStyle: number; isOverflowing: boolean; rowsOccupied: number };
+    };
+
+    const applyHeight = (target: number | null, isOverflowing: boolean) => {
+      if (target == null) {
+        if (heightRef.current !== null) {
+          el.style.height = '';
+          heightRef.current = null;
+        }
+
+        const overflowValue = isOverflowing ? 'auto' : 'hidden';
+        if (el.style.overflowY !== overflowValue) {
+          el.style.overflowY = overflowValue;
+        }
+
+        return;
+      }
+
+      if (heightRef.current !== target) {
+        el.style.height = `${target}px`;
+        heightRef.current = target;
+      }
+
+      const overflowValue = isOverflowing ? 'auto' : 'hidden';
+      if (el.style.overflowY !== overflowValue) {
+        el.style.overflowY = overflowValue;
+      }
+    };
+
     const resize = () => {
-      el.style.height = 'auto';
-      const lineHeight = parseFloat(getComputedStyle(el).lineHeight) || 24;
-      const min = minRows != null ? minRows * lineHeight : 0;
-      const maxPx = maxRows != null ? maxRows * lineHeight : Infinity;
-      const target = Math.min(maxPx, Math.max(min, el.scrollHeight));
-      el.style.height = `${target}px`;
-      el.style.overflowY = el.scrollHeight > target ? 'auto' : 'hidden';
+      const styles = calculate();
+      if (!styles) {
+        return;
+      }
+
+      const { outerHeightStyle, isOverflowing, rowsOccupied } = styles;
+
+      // only apply height if we are not at minimum rows yet
+      if (minRows != null) {
+        const needsMoreThanMin = rowsOccupied > Number(minRows) + 0.0001;
+
+        if (!needsMoreThanMin) {
+          applyHeight(null, isOverflowing);
+          return;
+        }
+      }
+
+      applyHeight(outerHeightStyle, isOverflowing);
     };
 
-    resize();
+    let rafId = 0 as number;
+    rafId = requestAnimationFrame(resize);
+
     el.addEventListener('input', resize);
     window.addEventListener('resize', resize);
 
+    let ro: ResizeObserver | null = null;
+    if (typeof ResizeObserver !== 'undefined') {
+      ro = new ResizeObserver(() => {
+        if (rafId) {
+          cancelAnimationFrame(rafId);
+        }
+        rafId = requestAnimationFrame(resize);
+      });
+      try {
+        ro.observe(el);
+        if (el.parentElement) {
+          ro.observe(el.parentElement);
+        }
+      } catch (err) {
+        // ignore observation errors
+      }
+    }
+
     return () => {
       el.removeEventListener('input', resize);
       window.removeEventListener('resize', resize);
+      if (rafId) {
+        cancelAnimationFrame(rafId);
+      }
+      if (ro) {
+        ro.disconnect();
+      }
     };
-  }, [inputRef, minRows, maxRows]);
+  }, [inputRef, minRows, maxRows, placeholder]);
 
   const element = useRenderElement('textarea', componentProps, {
     ref: forwardedRef || undefined,
@@ -157,7 +322,7 @@ export const Textarea = React.forwardRef(function Textarea(
           ? {
               style: {
                 ...(style as React.CSSProperties),
-                height: `${minRows * 24}px`,
+                height: 'auto',
                 resize: 'none',
               },
             }
@@ -198,7 +363,29 @@ export const Textarea = React.forwardRef(function Textarea(
     stateAttributesMapping: fieldValidityMapping,
   });
 
-  return element;
+  return React.createElement(
+    React.Fragment,
+    null,
+    element,
+    React.createElement('textarea', {
+      'aria-hidden': true,
+      readOnly: true,
+      ref: hiddenTextareaRef,
+      tabIndex: -1,
+      style: {
+        visibility: 'hidden',
+        position: 'absolute',
+        overflow: 'hidden',
+        height: 0,
+        top: 0,
+        left: 0,
+        transform: 'translateZ(0)',
+        paddingTop: 0,
+        paddingBottom: 0,
+        ...(style as React.CSSProperties),
+      },
+    }),
+  );
 });
 
 export namespace Textarea {
@@ -207,9 +394,6 @@ export namespace Textarea {
   export interface Props extends BaseUIComponentProps<'textarea', State> {
     /**
      * Enable automatic height resizing by setting the minimum number of rows.
-     *
-     * Prefer the CSS property `field-sizing: content` when supported (not
-     * supported in Safari and Firefox).
      */
     minRows?: number;
     /**

From f346f3fea27b8b905f1c0754eb2c218e5635999b Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Sat, 4 Oct 2025 10:06:52 -0500
Subject: [PATCH 11/18] Extracts height calc and debounces resize

Extracts the textarea height calculation into a reusable utility and isolates the expensive measurement logic.

Reduces layout thrashing by tracking last-applied height and overflow to avoid redundant DOM writes, and introduces debounced scheduling (~166ms) for resize/observer events while using immediate RAF for input events to keep input responsive.

Adds proper timer/observer cleanup and a default rows fallback to ensure consistent initial sizing and improved runtime performance.
---
 packages/react/src/textarea/Textarea.tsx      | 199 ++++++++----------
 .../src/textarea/calculateTextareaHeight.ts   | 111 ++++++++++
 2 files changed, 193 insertions(+), 117 deletions(-)
 create mode 100644 packages/react/src/textarea/calculateTextareaHeight.ts

diff --git a/packages/react/src/textarea/Textarea.tsx b/packages/react/src/textarea/Textarea.tsx
index c375f9b1cb..d7e18bd907 100644
--- a/packages/react/src/textarea/Textarea.tsx
+++ b/packages/react/src/textarea/Textarea.tsx
@@ -15,6 +15,7 @@ import {
   BaseUIChangeEventDetails,
   createChangeEventDetails,
 } from '../utils/createBaseUIEventDetails';
+import { calculateTextareaHeight } from './calculateTextareaHeight';
 
 /**
  * A native textarea element that automatically works with [Field](https://base-ui.com/react/components/field).
@@ -129,129 +130,58 @@ export const Textarea = React.forwardRef(function Textarea(
       return undefined;
     }
 
-    const getStyleValue = (str: string) => parseInt(str, 10) || 0;
-
-    const calculate = () => {
-      const computedStyle = getComputedStyle(el);
-
-      let width = computedStyle.width;
-      if (!width || width === '0px') {
-        const rect = el.getBoundingClientRect();
-        width = rect.width ? `${rect.width}px` : width;
-      }
-
-      if (!width || width === '0px') {
-        return null;
-      }
-
-      const styleToCopy = [
-        'boxSizing',
-        'width',
-        'paddingTop',
-        'paddingBottom',
-        'paddingLeft',
-        'paddingRight',
-        'borderTopWidth',
-        'borderBottomWidth',
-        'fontFamily',
-        'fontSize',
-        'fontWeight',
-        'fontStyle',
-        'letterSpacing',
-        'textTransform',
-        'textIndent',
-        'lineHeight',
-        'whiteSpace',
-      ];
-
-      hidden.style.width = width;
-      for (const propName of styleToCopy) {
-        hidden.style[propName as keyof Omit<CSSStyleDeclaration, 'length' | 'parentRule'>] = (computedStyle as any)[propName];
-      }
-
-      hidden.style.whiteSpace =
-        computedStyle.whiteSpace === 'pre-wrap' || computedStyle.whiteSpace === 'pre-line'
-          ? computedStyle.whiteSpace
-          : 'pre-wrap';
-
-      hidden.value = el.value || placeholder || 'x';
-      if (hidden.value.slice(-1) === '\n') {
-        hidden.value += ' ';
-      }
-
-      const boxSizing = computedStyle.boxSizing;
-      const paddingTop = getStyleValue(computedStyle.paddingTop);
-      const paddingBottom = getStyleValue(computedStyle.paddingBottom);
-      const padding = paddingTop + paddingBottom;
-      const border =
-        getStyleValue(computedStyle.borderBottomWidth) +
-        getStyleValue(computedStyle.borderTopWidth);
-
-      const innerScrollHeight = hidden.scrollHeight;
-
-      hidden.value = 'x';
-      const singleRowScrollHeight = hidden.scrollHeight || 1;
-      const singleRowContentHeight = Math.max(singleRowScrollHeight - padding, 1);
-
-      const currentContentHeight = Math.max(innerScrollHeight - padding, 0);
-
-      let desiredContentHeight = currentContentHeight;
-      if (minRows) {
-        desiredContentHeight = Math.max(
-          Number(minRows) * singleRowContentHeight,
-          desiredContentHeight,
-        );
-      }
-      if (maxRows) {
-        desiredContentHeight = Math.min(
-          Number(maxRows) * singleRowContentHeight,
-          desiredContentHeight,
-        );
-      }
-      desiredContentHeight = Math.max(desiredContentHeight, singleRowContentHeight);
-
-      const outerHeightStyle =
-        boxSizing === 'border-box' ? desiredContentHeight + padding + border : desiredContentHeight;
-
-      const isOverflowing = currentContentHeight > desiredContentHeight + 1;
-
-      const rowsOccupied = currentContentHeight / singleRowContentHeight;
-
-      return {
-        outerHeightStyle,
-        isOverflowing,
-        rowsOccupied,
-      } as { outerHeightStyle: number; isOverflowing: boolean; rowsOccupied: number };
-    };
+    // Track the last applied overflow state so we avoid redundant writes.
+    let lastIsOverflowing: boolean | null = null;
 
     const applyHeight = (target: number | null, isOverflowing: boolean) => {
+      // Only write to the DOM when something actually changed.
       if (target == null) {
-        if (heightRef.current !== null) {
+        const didClearHeight = heightRef.current !== null;
+        const didOverflowChange = lastIsOverflowing !== isOverflowing;
+
+        if (didClearHeight) {
           el.style.height = '';
           heightRef.current = null;
         }
 
-        const overflowValue = isOverflowing ? 'auto' : 'hidden';
-        if (el.style.overflowY !== overflowValue) {
-          el.style.overflowY = overflowValue;
+        if (didOverflowChange) {
+          const overflowValue = isOverflowing ? '' : 'hidden';
+          if (el.style.overflowY !== overflowValue) {
+            el.style.overflowY = overflowValue;
+          }
+          lastIsOverflowing = isOverflowing;
         }
 
         return;
       }
 
-      if (heightRef.current !== target) {
+      const didHeightChange = heightRef.current !== target;
+      const didOverflowChange = lastIsOverflowing !== isOverflowing;
+
+      if (didHeightChange) {
         el.style.height = `${target}px`;
         heightRef.current = target;
       }
 
-      const overflowValue = isOverflowing ? 'auto' : 'hidden';
-      if (el.style.overflowY !== overflowValue) {
-        el.style.overflowY = overflowValue;
+      if (didOverflowChange) {
+        const overflowValue = isOverflowing ? '' : 'hidden';
+        if (el.style.overflowY !== overflowValue) {
+          el.style.overflowY = overflowValue;
+        }
+        lastIsOverflowing = isOverflowing;
       }
     };
 
-    const resize = () => {
-      const styles = calculate();
+    // performResize contains the expensive measurement call. Keep it isolated so
+    // we can schedule/debounce it differently depending on the event source.
+    const performResize = () => {
+      const styles = calculateTextareaHeight(
+        el as unknown as HTMLTextAreaElement,
+        hidden as unknown as HTMLTextAreaElement,
+        placeholder,
+        minRows,
+        maxRows,
+      );
       if (!styles) {
         return;
       }
@@ -271,19 +201,52 @@ export const Textarea = React.forwardRef(function Textarea(
       applyHeight(outerHeightStyle, isOverflowing);
     };
 
-    let rafId = 0 as number;
-    rafId = requestAnimationFrame(resize);
+    // Debounce identifier used for less-frequent triggers (resize, RO).
+    let debounceTimeoutId: ReturnType<typeof setTimeout> | null = null;
+    let rafId = 0;
+
+    const schedulePerformResizeDebounced = () => {
+      // Debounce expensive measurements similar to MUI to avoid doing them too frequently.
+      const DEBOUNCE_MS = 166; // ~6fps; good tradeoff for resize/RO events
+      if (debounceTimeoutId) {
+        clearTimeout(debounceTimeoutId);
+      }
+      debounceTimeoutId = setTimeout(() => {
+        if (rafId) {
+          cancelAnimationFrame(rafId);
+        }
+        rafId = requestAnimationFrame(performResize);
+        debounceTimeoutId = null;
+      }, DEBOUNCE_MS);
+    };
+
+    const schedulePerformResizeImmediate = () => {
+      // For input events we want a more immediate response; schedule via RAF.
+      if (debounceTimeoutId) {
+        clearTimeout(debounceTimeoutId);
+        debounceTimeoutId = null;
+      }
+      if (rafId) {
+        cancelAnimationFrame(rafId);
+      }
+      rafId = requestAnimationFrame(performResize);
+    };
+
+    // Initial measurement
+    rafId = requestAnimationFrame(performResize);
 
-    el.addEventListener('input', resize);
-    window.addEventListener('resize', resize);
+    const onInput = () => {
+      schedulePerformResizeImmediate();
+    };
+
+    el.addEventListener('input', onInput);
+    window.addEventListener('resize', schedulePerformResizeDebounced);
 
     let ro: ResizeObserver | null = null;
     if (typeof ResizeObserver !== 'undefined') {
       ro = new ResizeObserver(() => {
-        if (rafId) {
-          cancelAnimationFrame(rafId);
-        }
-        rafId = requestAnimationFrame(resize);
+        // Use the debounced scheduler for ResizeObserver notifications.
+        schedulePerformResizeDebounced();
       });
       try {
         ro.observe(el);
@@ -296,11 +259,14 @@ export const Textarea = React.forwardRef(function Textarea(
     }
 
     return () => {
-      el.removeEventListener('input', resize);
-      window.removeEventListener('resize', resize);
+      el.removeEventListener('input', onInput);
+      window.removeEventListener('resize', schedulePerformResizeDebounced);
       if (rafId) {
         cancelAnimationFrame(rafId);
       }
+      if (debounceTimeoutId) {
+        clearTimeout(debounceTimeoutId);
+      }
       if (ro) {
         ro.disconnect();
       }
@@ -316,13 +282,12 @@ export const Textarea = React.forwardRef(function Textarea(
         disabled,
         name,
         ref: inputRef,
-        ...(minRows != null ? { rows: minRows } : {}),
+        rows: minRows || 2,
         'aria-labelledby': labelId,
-        ...(minRows != null && !(style as any)?.height
+        ...(minRows != null || maxRows != null
           ? {
               style: {
                 ...(style as React.CSSProperties),
-                height: 'auto',
                 resize: 'none',
               },
             }
diff --git a/packages/react/src/textarea/calculateTextareaHeight.ts b/packages/react/src/textarea/calculateTextareaHeight.ts
new file mode 100644
index 0000000000..a9ad96f1ea
--- /dev/null
+++ b/packages/react/src/textarea/calculateTextareaHeight.ts
@@ -0,0 +1,111 @@
+export interface CalculateTextareaHeightResult {
+  outerHeightStyle: number;
+  isOverflowing: boolean;
+  rowsOccupied: number;
+}
+
+/**
+ * Calculate the desired outer height, whether content is overflowing and the rows occupied
+ * for an auto-resizing textarea. This mirrors the logic previously embedded inside
+ * Textarea.tsx so the layout effect can stay concise.
+ */
+export function calculateTextareaHeight(
+  el: HTMLTextAreaElement,
+  hidden: HTMLTextAreaElement,
+  placeholder?: string,
+  minRows?: number,
+  maxRows?: number,
+): CalculateTextareaHeightResult | null {
+  if (!el || !hidden) {
+    return null;
+  }
+
+  const getStyleValue = (str: string) => parseInt(str, 10) || 0;
+
+  const computedStyle = getComputedStyle(el);
+
+  let width = computedStyle.width;
+  if (!width || width === '0px') {
+    const rect = el.getBoundingClientRect();
+    width = rect.width ? `${rect.width}px` : width;
+  }
+
+  if (!width || width === '0px') {
+    return null;
+  }
+
+  const styleToCopy = [
+    'boxSizing',
+    'width',
+    'paddingTop',
+    'paddingBottom',
+    'paddingLeft',
+    'paddingRight',
+    'borderTopWidth',
+    'borderBottomWidth',
+    'fontFamily',
+    'fontSize',
+    'fontWeight',
+    'fontStyle',
+    'letterSpacing',
+    'textTransform',
+    'textIndent',
+    'lineHeight',
+    'whiteSpace',
+  ];
+
+  hidden.style.width = width;
+  for (const propName of styleToCopy) {
+    // cast because CSSStyleDeclaration is readonly for some props in TS defs
+    (hidden.style as any)[propName] = (computedStyle as any)[propName];
+  }
+
+  hidden.style.whiteSpace =
+    computedStyle.whiteSpace === 'pre-wrap' || computedStyle.whiteSpace === 'pre-line'
+      ? computedStyle.whiteSpace
+      : 'pre-wrap';
+
+  hidden.value = el.value || placeholder || 'x';
+  if (hidden.value.slice(-1) === '\n') {
+    hidden.value += ' ';
+  }
+
+  const boxSizing = computedStyle.boxSizing;
+  const paddingTop = getStyleValue(computedStyle.paddingTop);
+  const paddingBottom = getStyleValue(computedStyle.paddingBottom);
+  const padding = paddingTop + paddingBottom;
+  const border =
+    getStyleValue(computedStyle.borderBottomWidth) + getStyleValue(computedStyle.borderTopWidth);
+
+  const innerScrollHeight = hidden.scrollHeight;
+
+  hidden.value = 'x';
+  const singleRowScrollHeight = hidden.scrollHeight || 1;
+  const singleRowContentHeight = Math.max(singleRowScrollHeight - padding, 1);
+
+  const currentContentHeight = Math.max(innerScrollHeight - padding, 0);
+
+  let desiredContentHeight = currentContentHeight;
+  if (minRows) {
+    desiredContentHeight = Math.max(Number(minRows) * singleRowContentHeight, desiredContentHeight);
+  }
+  if (maxRows) {
+    desiredContentHeight = Math.min(Number(maxRows) * singleRowContentHeight, desiredContentHeight);
+  }
+  desiredContentHeight = Math.max(desiredContentHeight, singleRowContentHeight);
+
+  const outerHeightStyle =
+    boxSizing === 'border-box' ? desiredContentHeight + padding + border : desiredContentHeight;
+
+  const isOverflowing = currentContentHeight > desiredContentHeight + 1;
+
+  const rowsOccupied = currentContentHeight / singleRowContentHeight;
+
+  return {
+    outerHeightStyle,
+    isOverflowing,
+    rowsOccupied,
+  };
+}
+
+export default calculateTextareaHeight;

From 0d9d6b601b98be55315500d521ac482a40a5d3c7 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Sat, 4 Oct 2025 10:41:09 -0500
Subject: [PATCH 12/18] Improve textarea style copying

Replace a hardcoded property list and unsafe direct assignments with iteration over computed styles and setProperty/getPropertyValue to copy relevant CSS keys.

This avoids TypeScript readonly casts, picks up actual computed property names (including vendor-prefixed variants), and makes style copying more robust and cross-browser resilient.
---
 .../src/textarea/calculateTextareaHeight.ts   | 44 ++++++++++---------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/packages/react/src/textarea/calculateTextareaHeight.ts b/packages/react/src/textarea/calculateTextareaHeight.ts
index a9ad96f1ea..c20dc6ee45 100644
--- a/packages/react/src/textarea/calculateTextareaHeight.ts
+++ b/packages/react/src/textarea/calculateTextareaHeight.ts
@@ -34,30 +34,32 @@ export function calculateTextareaHeight(
     return null;
   }
 
-  const styleToCopy = [
-    'boxSizing',
-    'width',
-    'paddingTop',
-    'paddingBottom',
-    'paddingLeft',
-    'paddingRight',
-    'borderTopWidth',
-    'borderBottomWidth',
-    'fontFamily',
-    'fontSize',
-    'fontWeight',
-    'fontStyle',
-    'letterSpacing',
-    'textTransform',
-    'textIndent',
-    'lineHeight',
-    'whiteSpace',
-  ];
+  const styleToCopy: string[] = [];
+  for (let i = 0; i < computedStyle.length; i += 1) {
+    const cssName = computedStyle[i];
+    if (!cssName) {
+      continue;
+    }
+
+    if (
+      cssName.includes('box-sizing') ||
+      cssName.includes('width') ||
+      cssName.includes('padding') ||
+      cssName.includes('border') ||
+      cssName.includes('font') ||
+      cssName.includes('letter-spacing') ||
+      cssName.includes('text-transform') ||
+      cssName.includes('text-indent') ||
+      cssName.includes('line-height') ||
+      cssName.includes('white-space')
+    ) {
+      styleToCopy.push(cssName);
+    }
+  }
 
   hidden.style.width = width;
   for (const propName of styleToCopy) {
-    // cast because CSSStyleDeclaration is readonly for some props in TS defs
-    (hidden.style as any)[propName] = (computedStyle as any)[propName];
+    hidden.style.setProperty(propName, computedStyle.getPropertyValue(propName));
   }
 
   hidden.style.whiteSpace =

From 8478164ca9b447c5bc1c449c7ee5108db2e0c88a Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Sat, 4 Oct 2025 11:12:26 -0500
Subject: [PATCH 13/18] adopting the MUI Firefox double-set workaround, leading
 to more stable textarea height calculations.

---
 packages/react/src/textarea/calculateTextareaHeight.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/react/src/textarea/calculateTextareaHeight.ts b/packages/react/src/textarea/calculateTextareaHeight.ts
index c20dc6ee45..47207cc81d 100644
--- a/packages/react/src/textarea/calculateTextareaHeight.ts
+++ b/packages/react/src/textarea/calculateTextareaHeight.ts
@@ -69,6 +69,9 @@ export function calculateTextareaHeight(
 
   hidden.value = el.value || placeholder || 'x';
   if (hidden.value.slice(-1) === '\n') {
+    // Certain fonts which overflow the line height will cause the textarea
+    // to report a different scrollHeight depending on whether the last line
+    // is empty. Make it non-empty to avoid this issue.
     hidden.value += ' ';
   }
 

From e96711a0c7798d1adee329f5d2ae9b28fa18d53b Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Sat, 4 Oct 2025 11:23:28 -0500
Subject: [PATCH 14/18] Remove forced resize none

Remove built-in inline "resize: none" from textarea rendering.

Allow consumers to control resizing via their own CSS instead of enforcing non-resizable behavior. Preserve existing value/rows handling; change affects styling only.
---
 packages/react/src/textarea/Textarea.tsx | 9 +--------
 1 file changed, 1 insertion(+), 8 deletions(-)

diff --git a/packages/react/src/textarea/Textarea.tsx b/packages/react/src/textarea/Textarea.tsx
index d7e18bd907..f006c7d3df 100644
--- a/packages/react/src/textarea/Textarea.tsx
+++ b/packages/react/src/textarea/Textarea.tsx
@@ -284,14 +284,7 @@ export const Textarea = React.forwardRef(function Textarea(
         ref: inputRef,
         rows: minRows || 2,
         'aria-labelledby': labelId,
-        ...(minRows != null || maxRows != null
-          ? {
-              style: {
-                ...(style as React.CSSProperties),
-                resize: 'none',
-              },
-            }
-          : { style }),
+        style,
         ...(isControlled ? { value } : { defaultValue }),
         onChange(event) {
           const inputValue = event.currentTarget.value;

From a6b97b8b3b65c5f0d184a7d3270b949400d81f56 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Sat, 4 Oct 2025 11:26:47 -0500
Subject: [PATCH 15/18] moved resize none to example CSS

---
 .../textarea/demos/infinite-resize/css-modules/index.module.css | 2 +-
 .../textarea/demos/infinite-resize/tailwind/index.tsx           | 2 +-
 .../textarea/demos/max-rows/css-modules/index.module.css        | 2 +-
 .../react/components/textarea/demos/max-rows/tailwind/index.tsx | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
index 96bc6cfbe5..8b0f3ed2e0 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/css-modules/index.module.css
@@ -12,7 +12,7 @@
   font-weight: normal;
   background-color: transparent;
   color: var(--color-gray-900);
-  resize: vertical;
+  resize: none;
 
   &:focus {
     outline: 2px solid var(--color-blue);
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
index d038ab6c78..3e41a428ff 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/infinite-resize/tailwind/index.tsx
@@ -6,7 +6,7 @@ export default function ExampleTextarea() {
     <Textarea
       placeholder="Type something…"
       minRows={4}
-      className="w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
+      className="w-full max-w-64 resize-none rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
     />
   );
 }
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
index 96bc6cfbe5..8b0f3ed2e0 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/css-modules/index.module.css
@@ -12,7 +12,7 @@
   font-weight: normal;
   background-color: transparent;
   color: var(--color-gray-900);
-  resize: vertical;
+  resize: none;
 
   &:focus {
     outline: 2px solid var(--color-blue);
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx
index fcf259abe8..6aa1958873 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/max-rows/tailwind/index.tsx
@@ -7,7 +7,7 @@ export default function ExampleTextarea() {
       placeholder="Type something…"
       minRows={4}
       maxRows={8}
-      className="w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
+      className="w-full max-w-64 resize-none rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
     />
   );
 }

From bea34bf7dd17e20b56398333f4c2a8f687d11ee3 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Sat, 4 Oct 2025 11:53:35 -0500
Subject: [PATCH 16/18] Add field-sizing demo

Adds interactive demos showing CSS field-sizing for the textarea component using CSS Modules and Tailwind, and updates documentation to explain the feature, browser support, and recommended fallback guidance.

Provides examples to let developers try native field-sizing behavior, clarifies current limited browser support, and notes a plan to adopt field-sizing by default once support reaches sufficient coverage.
---
 .../field-sizing/css-modules/index.module.css | 22 +++++++++++++++++++
 .../demos/field-sizing/css-modules/index.tsx  |  7 ++++++
 .../textarea/demos/field-sizing/index.ts      |  3 +++
 .../demos/field-sizing/tailwind/index.tsx     | 11 ++++++++++
 .../react/components/textarea/page.mdx        | 14 ++++++++++++
 5 files changed, 57 insertions(+)
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/css-modules/index.module.css
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/css-modules/index.tsx
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/index.ts
 create mode 100644 docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/tailwind/index.tsx

diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/css-modules/index.module.css b/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/css-modules/index.module.css
new file mode 100644
index 0000000000..cffe6190c0
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/css-modules/index.module.css
@@ -0,0 +1,22 @@
+.Textarea {
+  box-sizing: border-box;
+  margin: 0;
+  border: 1px solid var(--color-gray-200);
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  max-width: 16rem;
+  border-radius: 0.375rem;
+  font-family: inherit;
+  font-size: 1rem;
+  line-height: 1.5rem;
+  font-weight: normal;
+  background-color: transparent;
+  color: var(--color-gray-900);
+  resize: vertical;
+  field-sizing: content;
+
+  &:focus {
+    outline: 2px solid var(--color-blue);
+    outline-offset: -1px;
+  }
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/css-modules/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/css-modules/index.tsx
new file mode 100644
index 0000000000..8ff81679f9
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/css-modules/index.tsx
@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { Textarea } from '@base-ui-components/react/textarea';
+import styles from './index.module.css';
+
+export default function ExampleTextarea() {
+  return <Textarea placeholder="Type something…" className={styles.Textarea} />;
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/index.ts b/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/index.ts
new file mode 100644
index 0000000000..80097d6015
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/index.ts
@@ -0,0 +1,3 @@
+'use client';
+export { default as CssModules } from './css-modules';
+export { default as Tailwind } from './tailwind';
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/tailwind/index.tsx b/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/tailwind/index.tsx
new file mode 100644
index 0000000000..a6bbf95ec9
--- /dev/null
+++ b/docs/src/app/(public)/(content)/react/components/textarea/demos/field-sizing/tailwind/index.tsx
@@ -0,0 +1,11 @@
+import * as React from 'react';
+import { Textarea } from '@base-ui-components/react/textarea';
+
+export default function ExampleTextarea() {
+  return (
+    <Textarea
+      placeholder="Type something…"
+      className="field-sizing-content w-full max-w-64 resize-y rounded-md border border-gray-200 px-3 py-2 text-base text-gray-900 focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
+    />
+  );
+}
diff --git a/docs/src/app/(public)/(content)/react/components/textarea/page.mdx b/docs/src/app/(public)/(content)/react/components/textarea/page.mdx
index ad3f0ea256..80aa11aa88 100644
--- a/docs/src/app/(public)/(content)/react/components/textarea/page.mdx
+++ b/docs/src/app/(public)/(content)/react/components/textarea/page.mdx
@@ -41,3 +41,17 @@ Setting both `minRows` and `maxRows` will make the textarea automatically resize
 The textarea works seamlessly with the [Form](/react/components/form) component and supports libraries like [Zod](https://zod.dev/) for schema validation.
 
 <Demo path="./demos/form" />
+
+### Field sizing
+
+[MDN: `field-sizing`](https://developer.mozilla.org/docs/Web/CSS/field-sizing) · [Can I Use](https://caniuse.com/?search=field-sizing)
+
+The CSS `field-sizing` property lets form fields size themselves to their content. For example, a `<textarea>` can grow or shrink as you type without JavaScript.
+
+Browser support is about **71 % globally**. Chrome 123+, Edge 123+, and Opera 109+ support it. Safari only recently added it in TP, and many others (Firefox, IE, Opera Mini, UC Browser, KaiOS) don't yet.
+
+Because support is incomplete, the demo may not work in older browsers or Safari `<26`. If the textarea doesn't resize, try a **current Chrome or Edge** build.
+
+> Once support passes ~90 %, we plan to switch the Textarea component to `field-sizing` by default, dropping the JS fallback.
+
+<Demo path="./demos/field-sizing" />

From fa6f22f541f321f716430148023e699d439b1ae7 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Sat, 4 Oct 2025 11:54:49 -0500
Subject: [PATCH 17/18] dedupe

---
 pnpm-lock.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 81b4ef7704..a8e7c05e6d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -12435,7 +12435,7 @@ snapshots:
       eslint-config-prettier: 10.1.8(eslint@9.36.0(jiti@2.5.1))
       eslint-import-resolver-typescript: 4.4.4(eslint-plugin-import@2.32.0(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1))
       eslint-module-utils: 2.12.1(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@4.4.4(eslint-plugin-import@2.32.0(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@4.4.4)(eslint@9.36.0(jiti@2.5.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@4.4.4(eslint-plugin-import@2.32.0(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.36.0(jiti@2.5.1))
       eslint-plugin-mocha: 11.1.0(eslint@9.36.0(jiti@2.5.1))
       eslint-plugin-react: 7.37.5(eslint@9.36.0(jiti@2.5.1))
@@ -16669,7 +16669,7 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@4.4.4)(eslint@9.36.0(jiti@2.5.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@4.4.4(eslint-plugin-import@2.32.0(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1))
     transitivePeerDependencies:
       - supports-color
 
@@ -16683,7 +16683,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@4.4.4)(eslint@9.36.0(jiti@2.5.1)):
+  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@4.4.4(eslint-plugin-import@2.32.0(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1)))(eslint@9.36.0(jiti@2.5.1)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9

From 35e5187db832d9328d216a977bcc04114b865137 Mon Sep 17 00:00:00 2001
From: Jacksonmills <jackson.mills@steelseries.com>
Date: Sat, 4 Oct 2025 16:09:46 -0500
Subject: [PATCH 18/18] cleanup comments

---
 packages/react/src/textarea/Textarea.tsx | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/packages/react/src/textarea/Textarea.tsx b/packages/react/src/textarea/Textarea.tsx
index f006c7d3df..d90d82e592 100644
--- a/packages/react/src/textarea/Textarea.tsx
+++ b/packages/react/src/textarea/Textarea.tsx
@@ -172,8 +172,6 @@ export const Textarea = React.forwardRef(function Textarea(
       }
     };
 
-    // performResize contains the expensive measurement call. Keep it isolated so
-    // we can schedule/debounce it differently depending on the event source.
     const performResize = () => {
       const styles = calculateTextareaHeight(
         el as unknown as HTMLTextAreaElement,
@@ -232,7 +230,6 @@ export const Textarea = React.forwardRef(function Textarea(
       rafId = requestAnimationFrame(performResize);
     };
 
-    // Initial measurement
     rafId = requestAnimationFrame(performResize);
 
     const onInput = () => {
@@ -245,7 +242,6 @@ export const Textarea = React.forwardRef(function Textarea(
     let ro: ResizeObserver | null = null;
     if (typeof ResizeObserver !== 'undefined') {
       ro = new ResizeObserver(() => {
-        // Use the debounced scheduler for ResizeObserver notifications.
         schedulePerformResizeDebounced();
       });
       try {