From bdb9460d0a9156dd541683e9eed57b5c1db91f4f Mon Sep 17 00:00:00 2001
From: cixzhang <cindyxz@meta.com>
Date: Wed, 22 Jul 2026 12:34:55 +0000
Subject: [PATCH 1/2] feat(inputs): add statusVariant to the bordered input
 family (#4187)

---
 .changeset/input-status-variant.md            |  7 ++++
 apps/storybook/stories/DateInput.stories.tsx  | 28 +++++++++++++++
 .../stories/DateRangeInput.stories.tsx        | 24 +++++++++++++
 apps/storybook/stories/FileInput.stories.tsx  | 24 +++++++++++++
 .../stories/MultiSelector.stories.tsx         | 29 +++++++++++++++
 .../storybook/stories/NumberInput.stories.tsx | 24 +++++++++++++
 .../storybook/stories/PowerSearch.stories.tsx | 28 +++++++++++++++
 apps/storybook/stories/Selector.stories.tsx   | 35 +++++++++++++++++++
 apps/storybook/stories/TextArea.stories.tsx   | 24 +++++++++++++
 apps/storybook/stories/TextInput.stories.tsx  | 24 +++++++++++++
 apps/storybook/stories/TimeInput.stories.tsx  | 28 +++++++++++++++
 apps/storybook/stories/Tokenizer.stories.tsx  | 26 ++++++++++++++
 apps/storybook/stories/Typeahead.stories.tsx  | 26 ++++++++++++++
 packages/core/src/DateInput/DateInput.doc.mjs | 15 ++++++++
 .../core/src/DateInput/DateInput.test.tsx     | 23 ++++++++++++
 packages/core/src/DateInput/DateInput.tsx     | 10 ++++++
 .../src/DateRangeInput/DateRangeInput.doc.mjs |  8 +++++
 .../DateRangeInput/DateRangeInput.test.tsx    | 23 ++++++++++++
 .../src/DateRangeInput/DateRangeInput.tsx     | 10 ++++++
 packages/core/src/FileInput/FileInput.doc.mjs | 15 ++++++++
 .../core/src/FileInput/FileInput.test.tsx     | 23 ++++++++++++
 packages/core/src/FileInput/FileInput.tsx     | 10 ++++++
 .../src/MultiSelector/MultiSelector.doc.mjs   |  9 +++++
 .../src/MultiSelector/MultiSelector.test.tsx  | 23 ++++++++++++
 .../core/src/MultiSelector/MultiSelector.tsx  | 10 ++++++
 .../core/src/NumberInput/NumberInput.doc.mjs  | 15 ++++++++
 .../core/src/NumberInput/NumberInput.test.tsx | 23 ++++++++++++
 packages/core/src/NumberInput/NumberInput.tsx | 10 ++++++
 .../core/src/PowerSearch/PowerSearch.doc.mjs  | 15 ++++++++
 .../core/src/PowerSearch/PowerSearch.test.tsx | 23 ++++++++++++
 packages/core/src/PowerSearch/PowerSearch.tsx | 11 +++++-
 packages/core/src/Selector/Selector.doc.mjs   |  7 ++++
 packages/core/src/Selector/Selector.test.tsx  | 23 ++++++++++++
 packages/core/src/Selector/Selector.tsx       | 10 ++++++
 packages/core/src/TextArea/TextArea.doc.mjs   | 15 ++++++++
 packages/core/src/TextArea/TextArea.test.tsx  | 23 ++++++++++++
 packages/core/src/TextArea/TextArea.tsx       | 10 ++++++
 packages/core/src/TextInput/TextInput.doc.mjs | 15 ++++++++
 .../core/src/TextInput/TextInput.test.tsx     | 23 ++++++++++++
 packages/core/src/TextInput/TextInput.tsx     | 10 ++++++
 packages/core/src/TimeInput/TimeInput.doc.mjs | 15 ++++++++
 .../core/src/TimeInput/TimeInput.test.tsx     | 23 ++++++++++++
 packages/core/src/TimeInput/TimeInput.tsx     | 10 ++++++
 packages/core/src/Tokenizer/Tokenizer.doc.mjs | 15 ++++++++
 .../core/src/Tokenizer/Tokenizer.test.tsx     | 23 ++++++++++++
 packages/core/src/Tokenizer/Tokenizer.tsx     | 10 ++++++
 packages/core/src/Typeahead/Typeahead.doc.mjs |  7 ++++
 .../core/src/Typeahead/Typeahead.test.tsx     | 23 ++++++++++++
 packages/core/src/Typeahead/Typeahead.tsx     | 10 ++++++
 49 files changed, 874 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/input-status-variant.md

diff --git a/.changeset/input-status-variant.md b/.changeset/input-status-variant.md
new file mode 100644
index 000000000000..68504ddce8df
--- /dev/null
+++ b/.changeset/input-status-variant.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] The bordered input family now accepts a `statusVariant` prop (`'attached' | 'detached'`, default `'attached'`) that forwards to the underlying `Field`, letting you float the status message below the input with spacing instead of overlapping it. Added to TextInput, TextArea, NumberInput, DateInput, DateRangeInput, TimeInput, Selector, MultiSelector, Typeahead, Tokenizer, FileInput, and PowerSearch. Non-breaking: the default matches today's behavior. (#4187)
+
+@cixzhang
diff --git a/apps/storybook/stories/DateInput.stories.tsx b/apps/storybook/stories/DateInput.stories.tsx
index 720471811754..11c4f10d0579 100644
--- a/apps/storybook/stories/DateInput.stories.tsx
+++ b/apps/storybook/stories/DateInput.stories.tsx
@@ -366,3 +366,31 @@ export const ClearableWithStatus: Story = {
     status: {type: 'error', message: 'Date is in the past'},
   },
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState<ISODateString | undefined>(
+      '2026-01-25' as ISODateString,
+    );
+    const [b, setB] = useState<ISODateString | undefined>(
+      '2026-01-25' as ISODateString,
+    );
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 280}}>
+        <DateInput
+          label="Attached (default)"
+          value={a}
+          onChange={setA}
+          status={{type: 'error', message: 'This date is not available'}}
+        />
+        <DateInput
+          label="Detached"
+          value={b}
+          onChange={setB}
+          status={{type: 'error', message: 'This date is not available'}}
+          statusVariant="detached"
+        />
+      </div>
+    );
+  },
+};
diff --git a/apps/storybook/stories/DateRangeInput.stories.tsx b/apps/storybook/stories/DateRangeInput.stories.tsx
index db147a678320..d01fd5032d43 100644
--- a/apps/storybook/stories/DateRangeInput.stories.tsx
+++ b/apps/storybook/stories/DateRangeInput.stories.tsx
@@ -333,3 +333,27 @@ export const AllVariations: Story = {
     );
   },
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState<DateRange | null>(null);
+    const [b, setB] = useState<DateRange | null>(null);
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 320}}>
+        <DateRangeInput
+          label="Attached (default)"
+          value={a}
+          onChange={setA}
+          status={{type: 'error', message: 'Please select a date range'}}
+        />
+        <DateRangeInput
+          label="Detached"
+          value={b}
+          onChange={setB}
+          status={{type: 'error', message: 'Please select a date range'}}
+          statusVariant="detached"
+        />
+      </div>
+    );
+  },
+};
diff --git a/apps/storybook/stories/FileInput.stories.tsx b/apps/storybook/stories/FileInput.stories.tsx
index 0aae44b88269..e71fee85a638 100644
--- a/apps/storybook/stories/FileInput.stories.tsx
+++ b/apps/storybook/stories/FileInput.stories.tsx
@@ -282,3 +282,27 @@ export const AllVariations: Story = {
     );
   },
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState<File | File[] | null>(null);
+    const [b, setB] = useState<File | File[] | null>(null);
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 320}}>
+        <FileInput
+          label="Attached (default)"
+          value={a}
+          onChange={setA}
+          status={{type: 'error', message: 'File must be under 10MB'}}
+        />
+        <FileInput
+          label="Detached"
+          value={b}
+          onChange={setB}
+          status={{type: 'error', message: 'File must be under 10MB'}}
+          statusVariant="detached"
+        />
+      </div>
+    );
+  },
+};
diff --git a/apps/storybook/stories/MultiSelector.stories.tsx b/apps/storybook/stories/MultiSelector.stories.tsx
index 31129b2e266f..0a3fb54b5c00 100644
--- a/apps/storybook/stories/MultiSelector.stories.tsx
+++ b/apps/storybook/stories/MultiSelector.stories.tsx
@@ -405,3 +405,32 @@ export const Clearable: Story = {
     placeholder: 'Select technologies...',
   },
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState<string[]>([]);
+    const [b, setB] = useState<string[]>([]);
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 300}}>
+        <MultiSelector
+          label="Attached (default)"
+          options={['Name', 'Email', 'Role']}
+          value={a}
+          onChange={setA}
+          status={{type: 'error', message: 'Select at least one column'}}
+          placeholder="Select..."
+        />
+        <MultiSelector
+          label="Detached"
+          options={['Name', 'Email', 'Role']}
+          value={b}
+          onChange={setB}
+          status={{type: 'error', message: 'Select at least one column'}}
+          statusVariant="detached"
+          placeholder="Select..."
+        />
+      </div>
+    );
+  },
+  decorators: [Story => <Story />],
+};
diff --git a/apps/storybook/stories/NumberInput.stories.tsx b/apps/storybook/stories/NumberInput.stories.tsx
index bbe2f378149d..ca16963abab6 100644
--- a/apps/storybook/stories/NumberInput.stories.tsx
+++ b/apps/storybook/stories/NumberInput.stories.tsx
@@ -555,3 +555,27 @@ export const ClearableWithUnits: Story = {
     max: 100,
   },
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState<number | null>(-5);
+    const [b, setB] = useState<number | null>(-5);
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 280}}>
+        <NumberInput
+          label="Attached (default)"
+          value={a}
+          onChange={setA}
+          status={{type: 'error', message: 'Must be a positive number'}}
+        />
+        <NumberInput
+          label="Detached"
+          value={b}
+          onChange={setB}
+          status={{type: 'error', message: 'Must be a positive number'}}
+          statusVariant="detached"
+        />
+      </div>
+    );
+  },
+};
diff --git a/apps/storybook/stories/PowerSearch.stories.tsx b/apps/storybook/stories/PowerSearch.stories.tsx
index 154a3b7cb433..f471a0665d96 100644
--- a/apps/storybook/stories/PowerSearch.stories.tsx
+++ b/apps/storybook/stories/PowerSearch.stories.tsx
@@ -1375,3 +1375,31 @@ export const DisabledWithMessage: Story = {
     placeholder: 'Search...',
   },
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState<PowerSearchFilter[]>([]);
+    const [b, setB] = useState<PowerSearchFilter[]>([]);
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 400}}>
+        <PowerSearch
+          config={basicConfig}
+          filters={a}
+          onChange={newFilters => setA([...newFilters])}
+          isLabelHidden={false}
+          label="Attached (default)"
+          status={{type: 'error', message: 'Add at least one filter'}}
+        />
+        <PowerSearch
+          config={basicConfig}
+          filters={b}
+          onChange={newFilters => setB([...newFilters])}
+          isLabelHidden={false}
+          label="Detached"
+          status={{type: 'error', message: 'Add at least one filter'}}
+          statusVariant="detached"
+        />
+      </div>
+    );
+  },
+};
diff --git a/apps/storybook/stories/Selector.stories.tsx b/apps/storybook/stories/Selector.stories.tsx
index 574d42388767..eaffea17797f 100644
--- a/apps/storybook/stories/Selector.stories.tsx
+++ b/apps/storybook/stories/Selector.stories.tsx
@@ -603,3 +603,38 @@ export const PlacementAbove: Story = {
     );
   },
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState<string | undefined>();
+    const [b, setB] = useState<string | undefined>();
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 280}}>
+        <Selector
+          label="Attached (default)"
+          options={[
+            {value: 'apple', label: 'Apple'},
+            {value: 'banana', label: 'Banana'},
+          ]}
+          value={a}
+          onChange={setA}
+          placeholder="Select a fruit..."
+          status={{type: 'error', message: 'Please select a fruit'}}
+        />
+        <Selector
+          label="Detached"
+          options={[
+            {value: 'apple', label: 'Apple'},
+            {value: 'banana', label: 'Banana'},
+          ]}
+          value={b}
+          onChange={setB}
+          placeholder="Select a fruit..."
+          status={{type: 'error', message: 'Please select a fruit'}}
+          statusVariant="detached"
+        />
+      </div>
+    );
+  },
+  decorators: [Story => <Story />],
+};
diff --git a/apps/storybook/stories/TextArea.stories.tsx b/apps/storybook/stories/TextArea.stories.tsx
index 45178076c5e2..ee55a25e419b 100644
--- a/apps/storybook/stories/TextArea.stories.tsx
+++ b/apps/storybook/stories/TextArea.stories.tsx
@@ -635,3 +635,27 @@ export const MaxLengthVariations: Story = {
     );
   },
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState('Too short');
+    const [b, setB] = useState('Too short');
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 320}}>
+        <TextArea
+          label="Attached (default)"
+          value={a}
+          onChange={setA}
+          status={{type: 'error', message: 'Must be at least 50 characters'}}
+        />
+        <TextArea
+          label="Detached"
+          value={b}
+          onChange={setB}
+          status={{type: 'error', message: 'Must be at least 50 characters'}}
+          statusVariant="detached"
+        />
+      </div>
+    );
+  },
+};
diff --git a/apps/storybook/stories/TextInput.stories.tsx b/apps/storybook/stories/TextInput.stories.tsx
index 4811311a2ad5..67b469099dbf 100644
--- a/apps/storybook/stories/TextInput.stories.tsx
+++ b/apps/storybook/stories/TextInput.stories.tsx
@@ -514,3 +514,27 @@ export const ClearableWithStatus: Story = {
     status: {type: 'error', message: 'Invalid email address'},
   },
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState('invalid@');
+    const [b, setB] = useState('invalid@');
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 280}}>
+        <TextInput
+          label="Attached (default)"
+          value={a}
+          onChange={setA}
+          status={{type: 'error', message: 'Enter a valid email'}}
+        />
+        <TextInput
+          label="Detached"
+          value={b}
+          onChange={setB}
+          status={{type: 'error', message: 'Enter a valid email'}}
+          statusVariant="detached"
+        />
+      </div>
+    );
+  },
+};
diff --git a/apps/storybook/stories/TimeInput.stories.tsx b/apps/storybook/stories/TimeInput.stories.tsx
index 41ef51200161..dda1f7bbd55b 100644
--- a/apps/storybook/stories/TimeInput.stories.tsx
+++ b/apps/storybook/stories/TimeInput.stories.tsx
@@ -367,3 +367,31 @@ export const AllVariations: Story = {
     );
   },
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState<ISOTimeString | undefined>(
+      '22:00' as ISOTimeString,
+    );
+    const [b, setB] = useState<ISOTimeString | undefined>(
+      '22:00' as ISOTimeString,
+    );
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 280}}>
+        <TimeInput
+          label="Attached (default)"
+          value={a}
+          onChange={setA}
+          status={{type: 'error', message: 'Must be during business hours'}}
+        />
+        <TimeInput
+          label="Detached"
+          value={b}
+          onChange={setB}
+          status={{type: 'error', message: 'Must be during business hours'}}
+          statusVariant="detached"
+        />
+      </div>
+    );
+  },
+};
diff --git a/apps/storybook/stories/Tokenizer.stories.tsx b/apps/storybook/stories/Tokenizer.stories.tsx
index a64abf7aa677..3c7bdeb450ff 100644
--- a/apps/storybook/stories/Tokenizer.stories.tsx
+++ b/apps/storybook/stories/Tokenizer.stories.tsx
@@ -422,3 +422,29 @@ export const DisabledWithMessage: Story = {
     disabledMessage: 'You need edit access to change members',
   },
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState<SearchableItem[]>([]);
+    const [b, setB] = useState<SearchableItem[]>([]);
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 320}}>
+        <Tokenizer
+          label="Attached (default)"
+          searchSource={userSource}
+          value={a}
+          onChange={items => setA(items)}
+          status={{type: 'error', message: 'Select at least one member'}}
+        />
+        <Tokenizer
+          label="Detached"
+          searchSource={userSource}
+          value={b}
+          onChange={items => setB(items)}
+          status={{type: 'error', message: 'Select at least one member'}}
+          statusVariant="detached"
+        />
+      </div>
+    );
+  },
+};
diff --git a/apps/storybook/stories/Typeahead.stories.tsx b/apps/storybook/stories/Typeahead.stories.tsx
index 58618ec48432..efebec4d2343 100644
--- a/apps/storybook/stories/Typeahead.stories.tsx
+++ b/apps/storybook/stories/Typeahead.stories.tsx
@@ -221,3 +221,29 @@ export const WithStartIcon: Story = {
   },
   name: 'With Start Icon',
 };
+
+export const StatusVariantComparison: Story = {
+  render: () => {
+    const [a, setA] = useState<SearchableItem | null>(null);
+    const [b, setB] = useState<SearchableItem | null>(null);
+    return (
+      <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 300}}>
+        <Typeahead
+          label="Attached (default)"
+          searchSource={fruitSource}
+          value={a}
+          onChange={setA}
+          status={{type: 'error', message: 'Please make a selection'}}
+        />
+        <Typeahead
+          label="Detached"
+          searchSource={fruitSource}
+          value={b}
+          onChange={setB}
+          status={{type: 'error', message: 'Please make a selection'}}
+          statusVariant="detached"
+        />
+      </div>
+    );
+  },
+};
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index fdab1deecf09..b5c51492da17 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -115,6 +115,13 @@ export const docs = {
       description:
         'Status indicator object for error, warning, or success states with a message.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -377,6 +384,13 @@ export const docsZh = {
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: '错误、警告或成功状态的状态指示对象，附带消息。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -478,6 +492,7 @@ export const docsDense = {
     placeholder: 'placeholder text in input',
     size: 'input control size',
     status: 'error/warning/success status w/ message',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     labelTooltip: 'tooltip text via info icon at label end',
     hasClear: 'Shows clear button when date is set. Clears value on click.',
     numberOfMonths: 'months shown simultaneously in calendar popover',
diff --git a/packages/core/src/DateInput/DateInput.test.tsx b/packages/core/src/DateInput/DateInput.test.tsx
index dc89738f0ee9..44868130d2ed 100644
--- a/packages/core/src/DateInput/DateInput.test.tsx
+++ b/packages/core/src/DateInput/DateInput.test.tsx
@@ -835,3 +835,26 @@ describe('DateInput', () => {
     });
   });
 });
+
+
+describe('DateInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <DateInput label="Date" onChange={() => {}} status={{type: 'error', message: 'Bad date'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <DateInput label="Date" onChange={() => {}} status={{type: 'error', message: 'Bad date'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/DateInput/DateInput.tsx b/packages/core/src/DateInput/DateInput.tsx
index a3355b4d68b3..a3272731ca5f 100644
--- a/packages/core/src/DateInput/DateInput.tsx
+++ b/packages/core/src/DateInput/DateInput.tsx
@@ -42,6 +42,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon} from '../Icon';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -259,6 +260,13 @@ export interface DateInputProps extends Omit<
    * If message is provided, displays below the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -315,6 +323,7 @@ export function DateInput({
   placeholder: placeholderFromProps,
   size: sizeProp,
   status,
+  statusVariant = 'attached',
   labelTooltip,
   hasClear = false,
   numberOfMonths = 1,
@@ -699,6 +708,7 @@ export function DateInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {inputWrapper}
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
index b9822b0794a1..cacc4d6c925d 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
+++ b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
@@ -127,6 +127,13 @@ export const docs = {
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: 'Status indicator for error, warning, or success states.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -296,6 +303,7 @@ export const docsDense = {
     placeholder: 'placeholder when empty',
     size: 'trigger size',
     status: 'error/warning/success status',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     labelTooltip: 'tooltip via info icon at label end',
     numberOfMonths: 'months in calendar (default 2)',
     changeAction:
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx b/packages/core/src/DateRangeInput/DateRangeInput.test.tsx
index 688d430ff4b6..f798ce41339f 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx
+++ b/packages/core/src/DateRangeInput/DateRangeInput.test.tsx
@@ -471,3 +471,26 @@ describe('DateRangeInput', () => {
     });
   });
 });
+
+
+describe('DateRangeInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <DateRangeInput label="Range" value={null} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <DateRangeInput label="Range" value={null} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.tsx b/packages/core/src/DateRangeInput/DateRangeInput.tsx
index f829db71fdc4..ac1abec1f3f6 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.tsx
+++ b/packages/core/src/DateRangeInput/DateRangeInput.tsx
@@ -43,6 +43,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -330,6 +331,13 @@ export interface DateRangeInputProps extends Omit<
    * Status indicator for the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -385,6 +393,7 @@ export function DateRangeInput({
   placeholder: placeholderFromProps,
   size: sizeProp,
   status,
+  statusVariant = 'attached',
   labelTooltip,
   numberOfMonths = 2,
   width,
@@ -529,6 +538,7 @@ export function DateRangeInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       <div
diff --git a/packages/core/src/FileInput/FileInput.doc.mjs b/packages/core/src/FileInput/FileInput.doc.mjs
index 74f9105eae44..52670c9c19d1 100644
--- a/packages/core/src/FileInput/FileInput.doc.mjs
+++ b/packages/core/src/FileInput/FileInput.doc.mjs
@@ -119,6 +119,13 @@ export const docs = {
       description:
         'Validation status: applies a colored border. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -246,6 +253,13 @@ export const docsZh = {
       type: "{type: 'error' | 'warning' | 'success', message?: string}",
       description: '验证状态。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
   ],
   theming: {
     targets: [
@@ -316,6 +330,7 @@ export const docsDense = {
     placeholder: 'Placeholder when no files selected.',
     mode: "Visual mode: 'input' (compact) or 'dropzone' (drag-and-drop).",
     status: 'Validation status; colored border. Message floats below.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     labelTooltip: 'Tooltip in info icon at label end.',
   },
 };
diff --git a/packages/core/src/FileInput/FileInput.test.tsx b/packages/core/src/FileInput/FileInput.test.tsx
index ab719e3a5166..839aefb6b342 100644
--- a/packages/core/src/FileInput/FileInput.test.tsx
+++ b/packages/core/src/FileInput/FileInput.test.tsx
@@ -800,3 +800,26 @@ describe('FileInput', () => {
     });
   });
 });
+
+
+describe('FileInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <FileInput label="Upload" value={null} onChange={() => {}} status={{type: 'error', message: 'Something went wrong'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <FileInput label="Upload" value={null} onChange={() => {}} status={{type: 'error', message: 'Something went wrong'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/FileInput/FileInput.tsx b/packages/core/src/FileInput/FileInput.tsx
index e79f5416eac6..0b16ce367922 100644
--- a/packages/core/src/FileInput/FileInput.tsx
+++ b/packages/core/src/FileInput/FileInput.tsx
@@ -41,6 +41,7 @@ import {
   InputClearButton,
   type InputStatus,
   type InputStatusType,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon, type IconName} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -358,6 +359,13 @@ export interface FileInputProps extends Omit<
    * Validation status for the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * Description text displayed below the label.
    */
@@ -414,6 +422,7 @@ export function FileInput({
   isRequired = false,
   isLoading = false,
   status: statusProp,
+  statusVariant = 'attached',
   description,
   placeholder,
   mode = 'input',
@@ -728,6 +737,7 @@ export function FileInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       <div
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
index 03be0ebf55c7..da488827f1ce 100644
--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -154,6 +154,13 @@ export const docs = {
           type: "{type: 'error' | 'warning' | 'success', message?: string}",
           description: 'Validation status with an optional message.',
         },
+        {
+          name: 'statusVariant',
+          type: "'attached' | 'detached'",
+          description:
+            'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+          default: "'attached'",
+        },
         {
           name: 'renderOption',
           type: '(option: MultiSelectorOptionData) => ReactNode',
@@ -248,6 +255,7 @@ export const docsZh = {
         isRequired: '将字段标记为必填。',
         isLoading: '在触发器中显示加载旋转器。',
         status: '带可选消息的验证状态。',
+        statusVariant: '状态消息的放置方式：attached 直接叠加在输入框下方；detached 作为独立元素浮于下方并留有间距。',
         renderOption:
           '每个可选选项的自定义渲染函数。不会用于分隔线、分组或全选行。',
         xstyle: '布局自定义的 StyleX 样式，必须是 stylex.create() 值。',
@@ -373,6 +381,7 @@ export const docsDense = {
         isRequired: 'marks required',
         isLoading: 'spinner in trigger',
         status: 'validation status w/ optional message',
+        statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
         renderOption:
           'custom render fn per selectable option; not dividers/sections/select-all',
         xstyle: 'StyleX layout styles; stylex.create() only',
diff --git a/packages/core/src/MultiSelector/MultiSelector.test.tsx b/packages/core/src/MultiSelector/MultiSelector.test.tsx
index 09b6c4e132c1..3b8f47e2bad8 100644
--- a/packages/core/src/MultiSelector/MultiSelector.test.tsx
+++ b/packages/core/src/MultiSelector/MultiSelector.test.tsx
@@ -1076,3 +1076,26 @@ describe('MultiSelector', () => {
     });
   });
 });
+
+
+describe('MultiSelector statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <MultiSelector label="Fruit" options={['Apple', 'Banana']} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <MultiSelector label="Fruit" options={['Apple', 'Banana']} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/MultiSelector/MultiSelector.tsx b/packages/core/src/MultiSelector/MultiSelector.tsx
index 014dcf8f1e80..99b58020bd30 100644
--- a/packages/core/src/MultiSelector/MultiSelector.tsx
+++ b/packages/core/src/MultiSelector/MultiSelector.tsx
@@ -37,6 +37,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputWrapperStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Divider} from '../Divider';
 import {Spinner} from '../Spinner';
@@ -479,6 +480,13 @@ export interface MultiSelectorProps<
    * Status indicator for the selector.
    */
   status?: MultiSelectorStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -593,6 +601,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   placeholder: placeholderFromProps,
   size: sizeProp,
   status,
+  statusVariant = 'attached',
   labelTooltip,
   startIcon,
   hasClear = false,
@@ -1383,6 +1392,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {multiSelectorContent}
diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjs
index f6eeba8b5d57..ce1b8fdd5c63 100644
--- a/packages/core/src/NumberInput/NumberInput.doc.mjs
+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs
@@ -94,6 +94,13 @@ export const docs = {
       type: "{type: 'error' | 'warning' | 'success', message?: string}",
       description: 'Validation status with optional message.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'min',
       type: 'number | null',
@@ -275,6 +282,13 @@ export const docsZh = {
       type: "{type: 'error' | 'warning' | 'success', message?: string}",
       description: '带可选消息的验证状态。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'min',
       type: 'number | null',
@@ -402,6 +416,7 @@ export const docsDense = {
     startIcon: 'Icon at input start.',
     labelIcon: 'Icon before label text.',
     status: 'Validation status w/ optional message.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     min: 'Minimum value allowed.',
     max: 'Maximum value allowed.',
     step: 'Step increment.',
diff --git a/packages/core/src/NumberInput/NumberInput.test.tsx b/packages/core/src/NumberInput/NumberInput.test.tsx
index 310aa2a5ded6..a1fc7d5b78a0 100644
--- a/packages/core/src/NumberInput/NumberInput.test.tsx
+++ b/packages/core/src/NumberInput/NumberInput.test.tsx
@@ -912,3 +912,26 @@ describe('keyboard clearing with hasClear (#3599)', () => {
     expect((input as HTMLInputElement).value).toBe('42');
   });
 });
+
+
+describe('NumberInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <NumberInput label="Amount" value={null} onChange={() => {}} status={{type: 'error', message: 'Must be positive'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <NumberInput label="Amount" value={null} onChange={() => {}} status={{type: 'error', message: 'Must be positive'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/NumberInput/NumberInput.tsx b/packages/core/src/NumberInput/NumberInput.tsx
index f23c15af44ce..275774203bca 100644
--- a/packages/core/src/NumberInput/NumberInput.tsx
+++ b/packages/core/src/NumberInput/NumberInput.tsx
@@ -44,6 +44,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -207,6 +208,13 @@ interface NumberInputPropsBase extends Omit<
    * If message is provided, displays a floating message box below the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * The size of the input.
    * - 'sm': Compact size (28px height)
@@ -375,6 +383,7 @@ export function NumberInput({
   startIcon,
   labelIcon,
   status,
+  statusVariant = 'attached',
   size: sizeProp,
   onChange,
   value,
@@ -710,6 +719,7 @@ export function NumberInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {inputWrapper}
diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
index 5f9d388713f6..a7084cb4a345 100644
--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs
+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
@@ -83,6 +83,13 @@ export const docs = {
       description:
         'Validation status object with type and optional message.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'maxTokenLength',
       type: 'number',
@@ -235,6 +242,13 @@ export const docsZh = {
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: '带有类型和可选消息的验证状态对象。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'maxTokenLength',
       type: 'number',
@@ -318,6 +332,7 @@ export const docsDense = {
     isReadOnly: 'Prevent adding, editing, or removing filters.',
     isDisabled: 'Disables entire component.',
     status: 'Validation status object w/ type + optional message.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     maxTokenLength: 'Max char length for filter value display in tokens.',
     popoverSaveButtonLabel: 'Label for save button in edit popover.',
     timezoneID: 'Timezone ID for date formatting (e.g. "America/New_York").',
diff --git a/packages/core/src/PowerSearch/PowerSearch.test.tsx b/packages/core/src/PowerSearch/PowerSearch.test.tsx
index a0c5a368d057..f852bed00e3a 100644
--- a/packages/core/src/PowerSearch/PowerSearch.test.tsx
+++ b/packages/core/src/PowerSearch/PowerSearch.test.tsx
@@ -404,3 +404,26 @@ describe('PowerSearch', () => {
     });
   });
 });
+
+
+describe('PowerSearch statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <PowerSearch config={config} filters={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <PowerSearch config={config} filters={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/PowerSearch/PowerSearch.tsx b/packages/core/src/PowerSearch/PowerSearch.tsx
index c11b2ed83018..2192d5d584f2 100644
--- a/packages/core/src/PowerSearch/PowerSearch.tsx
+++ b/packages/core/src/PowerSearch/PowerSearch.tsx
@@ -37,7 +37,7 @@ import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {Icon} from '../Icon';
 import type {IconType} from '../Icon';
 import type {IconName} from '../Icon/globalIconRegistry';
-import type {InputStatus} from '../Field';
+import type {InputStatus, FieldStatusVariant} from '../Field';
 import {usePopover} from '../Popover/usePopover';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {
@@ -383,6 +383,13 @@ export interface PowerSearchProps extends Omit<
   onBlur?: (e: React.FocusEvent) => void;
   /** Validation status. */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /** Max width for dropdown menu. */
   menuWidth?: number;
   /** Max display length for filter token values. @default 40 */
@@ -527,6 +534,7 @@ export function PowerSearch({
   onFocus,
   onBlur,
   status,
+  statusVariant = 'attached',
   maxTokenLength = 40,
   popoverSaveButtonLabel: popoverSaveButtonLabelFromProps,
   timezoneID,
@@ -1033,6 +1041,7 @@ export function PowerSearch({
           hasEntriesOnFocus
           debounceMs={0}
           status={status}
+          statusVariant={statusVariant}
           onFocus={onFocus}
           onBlur={onBlur}
           xstyle={xstyle}
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index 9cb8718c5a46..a19dbde75b91 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -128,6 +128,13 @@ export const docs = {
       type: "{type: 'error' | 'warning' | 'success', message?: string}",
       description: 'Validation status with an optional message.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'renderOption',
       type: '(option: SelectorOptionData) => ReactNode',
diff --git a/packages/core/src/Selector/Selector.test.tsx b/packages/core/src/Selector/Selector.test.tsx
index a28102738928..b220a5e6f913 100644
--- a/packages/core/src/Selector/Selector.test.tsx
+++ b/packages/core/src/Selector/Selector.test.tsx
@@ -1004,3 +1004,26 @@ describe('Selector', () => {
     });
   });
 });
+
+
+describe('Selector statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <Selector label="Fruit" options={['Apple', 'Banana']} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <Selector label="Fruit" options={['Apple', 'Banana']} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/Selector/Selector.tsx b/packages/core/src/Selector/Selector.tsx
index e177ce34ad2a..ab5decaa0a5e 100644
--- a/packages/core/src/Selector/Selector.tsx
+++ b/packages/core/src/Selector/Selector.tsx
@@ -37,6 +37,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputWrapperStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Divider} from '../Divider';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
@@ -433,6 +434,13 @@ interface SelectorPropsBase<
    * If message is provided, displays a message box below the selector.
    */
   status?: SelectorStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -588,6 +596,7 @@ export function Selector<T extends SelectorOptionType>(
     placeholder: placeholderFromProps,
     size: sizeProp,
     status,
+    statusVariant = 'attached',
     labelTooltip,
     startIcon,
     htmlName,
@@ -1150,6 +1159,7 @@ export function Selector<T extends SelectorOptionType>(
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {selectorContent}
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index d1cfdd4c188f..a2ea1e54ad06 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -106,6 +106,13 @@ export const docs = {
       description:
         'Status indicator that applies a colored border and icon. An optional message is displayed in a floating box below the textarea.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -279,6 +286,13 @@ export const docsZh = {
       type: "{ type: 'warning' | 'error' | 'success'; message?: string }",
       description: '应用彩色边框和图标的状态指示器。可选消息显示在文本域下方的浮动框中。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -389,6 +403,7 @@ export const docsDense = {
     rows: 'Visible text rows.',
     maxLength: 'Max chars allowed. Shows counter (current/max) below textarea. No native enforcement.',
     status: 'Colored border+icon status. Optional floating message below textarea.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     labelTooltip: 'Tooltip in info icon at label end.',
     startIcon: 'Icon inside leading edge of textarea wrapper.',
     hasSpellCheck: 'Enables/disables browser spell checking.',
diff --git a/packages/core/src/TextArea/TextArea.test.tsx b/packages/core/src/TextArea/TextArea.test.tsx
index 864f3d5418c8..bc88518dad8c 100644
--- a/packages/core/src/TextArea/TextArea.test.tsx
+++ b/packages/core/src/TextArea/TextArea.test.tsx
@@ -728,3 +728,26 @@ describe('TextArea', () => {
     });
   });
 });
+
+
+describe('TextArea statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <TextArea label="Bio" value="" onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <TextArea label="Bio" value="" onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/TextArea/TextArea.tsx b/packages/core/src/TextArea/TextArea.tsx
index 561f0dcf03ec..4013d5209592 100644
--- a/packages/core/src/TextArea/TextArea.tsx
+++ b/packages/core/src/TextArea/TextArea.tsx
@@ -40,6 +40,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -217,6 +218,13 @@ export interface TextAreaProps extends Omit<
    * If message is provided, displays a floating message box below the textarea.
    */
   status?: TextAreaStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
    * (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
@@ -298,6 +306,7 @@ export function TextArea({
   isDisabled = false,
   disabledMessage,
   status,
+  statusVariant = 'attached',
   labelTooltip,
   startIcon,
   hasSpellCheck = true,
@@ -412,6 +421,7 @@ export function TextArea({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       <div
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
index a48a35bde5d6..9f5d277100be 100644
--- a/packages/core/src/TextInput/TextInput.doc.mjs
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -114,6 +114,13 @@ export const docs = {
       description:
         'Validation status: applies a colored border and status icon. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'hasClear',
       type: 'boolean',
@@ -274,6 +281,13 @@ export const docsZh = {
       description:
         '验证状态：应用彩色边框和状态图标。如果提供了 message，在输入框下方显示浮动消息。错误类型还会设置 aria-invalid。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'hasClear',
       type: 'boolean',
@@ -368,6 +382,7 @@ export const docsDense = {
     labelTooltip: 'Tooltip in info icon at label end.',
     startIcon: 'SVG icon at input start (e.g. heroicons or lucide).',
     status: 'Validation status; colored border+icon. Message floats below. Error sets aria-invalid.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     hasClear: 'Shows clear button when input has value. Clears value on click.',
     hasAutoFocus: 'Auto-focus input on mount.',
     htmlName: 'HTML name attr for form submissions.',
diff --git a/packages/core/src/TextInput/TextInput.test.tsx b/packages/core/src/TextInput/TextInput.test.tsx
index 331e282d3c94..673de915c04f 100644
--- a/packages/core/src/TextInput/TextInput.test.tsx
+++ b/packages/core/src/TextInput/TextInput.test.tsx
@@ -659,3 +659,26 @@ describe('TextInput', () => {
     });
   });
 });
+
+
+describe('TextInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <TextInput label="Email" value="" onChange={() => {}} status={{type: 'error', message: 'Invalid email'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <TextInput label="Email" value="" onChange={() => {}} status={{type: 'error', message: 'Invalid email'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/TextInput/TextInput.tsx b/packages/core/src/TextInput/TextInput.tsx
index 4ac62c06729d..ee71fc91b388 100644
--- a/packages/core/src/TextInput/TextInput.tsx
+++ b/packages/core/src/TextInput/TextInput.tsx
@@ -44,6 +44,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -198,6 +199,13 @@ export interface TextInputProps extends Omit<
    * If message is provided, displays a floating message box below the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * The size of the input.
    * - 'sm': Compact size (18px height)
@@ -280,6 +288,7 @@ export function TextInput({
   disabledMessage,
   startIcon,
   status,
+  statusVariant = 'attached',
   size: sizeProp,
   onChange,
   changeAction,
@@ -495,6 +504,7 @@ export function TextInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {inputWrapper}
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index 5f7c91b5347f..643c26d7802d 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -229,6 +229,13 @@ export const docs = {
       description:
         'Status indicator that colors the border and displays an icon. When a message is provided it is rendered below the input.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -372,6 +379,13 @@ export const docsZh = {
       description:
         '为边框着色并显示图标的状态指示器。当提供消息时，消息渲染在输入框下方。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -545,6 +559,7 @@ export const docsDense = {
     placeholder: 'Placeholder when empty. Focused+empty shows format hint.',
     size: 'Input element height.',
     status: 'Colored border+icon. Message rendered below input.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     labelTooltip: 'Tooltip as info icon at label row end.',
     xstyle:
       'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
diff --git a/packages/core/src/TimeInput/TimeInput.test.tsx b/packages/core/src/TimeInput/TimeInput.test.tsx
index e6c0d7e9c9e3..a5b56fb4e62d 100644
--- a/packages/core/src/TimeInput/TimeInput.test.tsx
+++ b/packages/core/src/TimeInput/TimeInput.test.tsx
@@ -496,3 +496,26 @@ describe('TimeInput', () => {
     });
   });
 });
+
+
+describe('TimeInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <TimeInput label="Start" value={undefined} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <TimeInput label="Start" value={undefined} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/TimeInput/TimeInput.tsx b/packages/core/src/TimeInput/TimeInput.tsx
index 173437ab85ab..a5e50227e4de 100644
--- a/packages/core/src/TimeInput/TimeInput.tsx
+++ b/packages/core/src/TimeInput/TimeInput.tsx
@@ -45,6 +45,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -296,6 +297,13 @@ export interface TimeInputProps extends Omit<
    * If message is provided, displays below the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -345,6 +353,7 @@ export function TimeInput({
   placeholder: placeholderFromProps,
   size: sizeProp,
   status,
+  statusVariant = 'attached',
   labelTooltip,
   width,
   xstyle,
@@ -707,6 +716,7 @@ export function TimeInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {inputWrapper}
diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
index 4d6bfbe2542e..93db62278223 100644
--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs
+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
@@ -88,6 +88,13 @@ export const docs = {
       description:
         'Validation status object with type and message for error/warning/success states.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'isLabelHidden',
       type: 'boolean',
@@ -300,6 +307,13 @@ export const docsZh = {
       description:
         '\u9a8c\u8bc1\u72b6\u6001\u5bf9\u8c61\uff0c\u5305\u542b\u7c7b\u578b\u548c\u6d88\u606f\uff0c\u7528\u4e8e\u9519\u8bef/\u8b66\u544a/\u6210\u529f\u72b6\u6001\u3002',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'isLabelHidden',
       type: 'boolean',
@@ -448,6 +462,7 @@ export const docsDense = {
     isDisabled: 'Disables input+all token interactions.',
     htmlName: 'HTML name attr; one hidden input per selected item id.',
     status: 'Validation status w/ type+message for error/warning/success.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     isLabelHidden: 'Visually hides label; keeps a11y.',
     description: 'Helper text below label.',
     isRequired: 'Marks field required.',
diff --git a/packages/core/src/Tokenizer/Tokenizer.test.tsx b/packages/core/src/Tokenizer/Tokenizer.test.tsx
index 0f9a0cda5897..d6d491025228 100644
--- a/packages/core/src/Tokenizer/Tokenizer.test.tsx
+++ b/packages/core/src/Tokenizer/Tokenizer.test.tsx
@@ -955,3 +955,26 @@ describe('Tokenizer', () => {
     });
   });
 });
+
+
+describe('Tokenizer statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <Tokenizer label="Members" searchSource={userSource} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <Tokenizer label="Members" searchSource={userSource} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/Tokenizer/Tokenizer.tsx b/packages/core/src/Tokenizer/Tokenizer.tsx
index e60c481b34b1..b11ce00d1a73 100644
--- a/packages/core/src/Tokenizer/Tokenizer.tsx
+++ b/packages/core/src/Tokenizer/Tokenizer.tsx
@@ -37,6 +37,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Token} from '../Token';
 import {renderIconSlot, type IconType} from '../Icon';
@@ -110,6 +111,13 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
   isOptional?: boolean;
   /** Validation status. */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * Icon to display at the start of the input.
    * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -369,6 +377,7 @@ export function Tokenizer<T extends SearchableItem>({
   isRequired = false,
   isOptional = false,
   status,
+  statusVariant = 'attached',
   startIcon,
   labelTooltip,
   searchSource,
@@ -879,6 +888,7 @@ export function Tokenizer<T extends SearchableItem>({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}
       xstyle={xstyle}
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index 9b241cbe9361..8b4ef430e03a 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -89,6 +89,13 @@ export const docs = {
       description:
         'Validation status object with type and message for error/warning/success states.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'renderItem',
       type: '(item: T) => ReactNode',
diff --git a/packages/core/src/Typeahead/Typeahead.test.tsx b/packages/core/src/Typeahead/Typeahead.test.tsx
index 7ae83c678b15..67d9275f8cb4 100644
--- a/packages/core/src/Typeahead/Typeahead.test.tsx
+++ b/packages/core/src/Typeahead/Typeahead.test.tsx
@@ -948,3 +948,26 @@ describe('Typeahead disabledMessage', () => {
     expect(input).not.toHaveAttribute('aria-disabled');
   });
 });
+
+
+describe('Typeahead statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <Typeahead label="Fruit" searchSource={fruitSource} value={null} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <Typeahead label="Fruit" searchSource={fruitSource} value={null} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
diff --git a/packages/core/src/Typeahead/Typeahead.tsx b/packages/core/src/Typeahead/Typeahead.tsx
index af01bbebaf0e..6582a5447bcf 100644
--- a/packages/core/src/Typeahead/Typeahead.tsx
+++ b/packages/core/src/Typeahead/Typeahead.tsx
@@ -36,6 +36,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Token} from '../Token';
 import {useTooltip} from '../Tooltip';
@@ -75,6 +76,13 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<
   isOptional?: boolean;
   /** Validation status. */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * Icon to display at the start of the input.
    * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -226,6 +234,7 @@ export function Typeahead<T extends SearchableItem>({
   isRequired = false,
   isOptional = false,
   status,
+  statusVariant = 'attached',
   startIcon,
   labelTooltip,
   searchSource,
@@ -500,6 +509,7 @@ export function Typeahead<T extends SearchableItem>({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}
       xstyle={xstyle}

From 9eceb972bdd0aa2e7c01425466181c904f49c417 Mon Sep 17 00:00:00 2001
From: cixzhang <cindyxz@meta.com>
Date: Fri, 24 Jul 2026 02:40:48 +0000
Subject: [PATCH 2/2] docs(TextInput): add statusVariant showcase block

---
 .../TextInput/TextInputStatusVariant.doc.mjs  | 13 +++++
 .../TextInput/TextInputStatusVariant.tsx      | 54 +++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 packages/cli/templates/blocks/components/TextInput/TextInputStatusVariant.doc.mjs
 create mode 100644 packages/cli/templates/blocks/components/TextInput/TextInputStatusVariant.tsx

diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputStatusVariant.doc.mjs b/packages/cli/templates/blocks/components/TextInput/TextInputStatusVariant.doc.mjs
new file mode 100644
index 000000000000..9dd246e5c559
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TextInput/TextInputStatusVariant.doc.mjs
@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'TextInput',
+  name: 'TextInput — Status variant',
+  displayName: 'TextInput — Status variant',
+  description: 'The statusVariant prop controls whether the status message is attached to the bordered input (default, overlapping directly below) or detached from it (floating below as a separate element with spacing).',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['TextInput', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputStatusVariant.tsx b/packages/cli/templates/blocks/components/TextInput/TextInputStatusVariant.tsx
new file mode 100644
index 000000000000..eb219340a718
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TextInput/TextInputStatusVariant.tsx
@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {Stack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function TextInputStatusVariant() {
+  const [attached, setAttached] = useState('sarah@');
+  const [detached, setDetached] = useState('sarah@');
+
+  return (
+    <div style={{width: 640}}>
+      <Stack direction="horizontal" gap={5}>
+        <Stack direction="vertical" gap={2}>
+          <Text type="label">attached (default)</Text>
+          <TextInput
+            label="Email"
+            value={attached}
+            onChange={setAttached}
+            placeholder="you@example.com"
+            statusVariant="attached"
+            status={{
+              type: 'error',
+              message: 'Please enter a valid email address.',
+            }}
+          />
+          <Text type="supporting">
+            Message overlaps directly below the input.
+          </Text>
+        </Stack>
+        <Stack direction="vertical" gap={2}>
+          <Text type="label">detached</Text>
+          <TextInput
+            label="Email"
+            value={detached}
+            onChange={setDetached}
+            placeholder="you@example.com"
+            statusVariant="detached"
+            status={{
+              type: 'error',
+              message: 'Please enter a valid email address.',
+            }}
+          />
+          <Text type="supporting">
+            Message floats below as a separate element with spacing.
+          </Text>
+        </Stack>
+      </Stack>
+    </div>
+  );
+}