From dcedd9cf9e7f728f47a1ac58d70a34f00de42958 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Sat, 29 Aug 2026 08:03:01 -0400
Subject: [PATCH] fix(*): Associate Mosaic Otp with its Field label

`<Otp.Root>`'s id now lands on the first slot instead of the `role="group"`
element, so a `<label htmlFor>` targets a real control. The first slot inherits
the group's accessible name; the rest stay positional. Adds `required` (applied
to each slot, since the hidden input is `readOnly` and barred from constraint
validation) and disables the hidden input alongside the field.
---
 .changeset/otp-mosaic-field.md                |   2 +
 .../headless/src/primitives/otp/README.md     |  11 +-
 .../src/primitives/otp/otp-context.ts         |  12 +++
 .../headless/src/primitives/otp/otp-input.tsx |  12 ++-
 .../headless/src/primitives/otp/otp-root.tsx  |  39 ++++++-
 .../headless/src/primitives/otp/otp.test.tsx  | 101 ++++++++++++++++++
 .../swingset/src/stories/otp.component.mdx    |  14 ++-
 .../src/stories/otp.component.stories.tsx     |  13 +++
 packages/swingset/src/stories/otp.mdx         |  37 ++++---
 .../ui/src/mosaic/components/otp/otp.test.tsx |  48 +++++++++
 packages/ui/src/mosaic/components/otp/otp.tsx |   7 ++
 11 files changed, 274 insertions(+), 22 deletions(-)
 create mode 100644 .changeset/otp-mosaic-field.md

diff --git a/.changeset/otp-mosaic-field.md b/.changeset/otp-mosaic-field.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/otp-mosaic-field.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/headless/src/primitives/otp/README.md b/packages/headless/src/primitives/otp/README.md
index 5e2d2f3f289..57f36f0909c 100644
--- a/packages/headless/src/primitives/otp/README.md
+++ b/packages/headless/src/primitives/otp/README.md
@@ -159,6 +159,13 @@ and the `Ctrl`/`Cmd` boundary jumps stay logical (first / last-entered).
 ## ARIA
 
 - `Root` is a `role="group"`; give it an `aria-label` (or `aria-labelledby`) describing the code.
-- Each `Input` gets a default `aria-label` of `"Character N of M"`, overridable per input.
+- `Root`'s `id` lands on the first `Input`, not the group, so a `<label htmlFor>` targets a real
+  control and clicking it focuses the code. Remaining slots take `${id}-2`, `${id}-3`, and so on.
+- The first `Input` inherits the group's name (from `aria-labelledby`, then `aria-label`), or is
+  left to a native `<label>`. The rest get a default `aria-label` of `"Character N of M"`,
+  overridable per input.
 - Slots use a roving tab index: `Tab` enters the group at the next empty slot and leaves in one step.
-- When `name` is set, the hidden form input is `aria-hidden` and removed from the tab order.
+- When `name` is set, the hidden form input is `aria-hidden`, removed from the tab order, and
+  disabled alongside the field so a disabled code submits nothing.
+- `required` is applied to each slot rather than the hidden input, which is `readOnly` and so barred
+  from constraint validation. A partially entered code fails validation on its first empty slot.
diff --git a/packages/headless/src/primitives/otp/otp-context.ts b/packages/headless/src/primitives/otp/otp-context.ts
index 69d2a188741..1d3ba557862 100644
--- a/packages/headless/src/primitives/otp/otp-context.ts
+++ b/packages/headless/src/primitives/otp/otp-context.ts
@@ -14,6 +14,9 @@ export interface OtpSlot {
   isFilled: boolean;
 }
 
+/** The naming attributes the first slot inherits from `<Otp.Root>`. */
+export type FirstInputLabel = { 'aria-labelledby': string } | { 'aria-label': string };
+
 export interface OtpContextValue {
   /** The current Otp value. */
   value: string;
@@ -21,6 +24,8 @@ export interface OtpContextValue {
   length: number;
   /** Whether the whole field is disabled. */
   disabled: boolean;
+  /** Whether every slot must be filled before the enclosing form submits. */
+  required: boolean;
   /** Whether every slot is filled. */
   complete: boolean;
   /** The allowed character set. */
@@ -36,6 +41,13 @@ export interface OtpContextValue {
   /** Focus the slot at `index` (clamped to range). */
   focus: (index: number) => void;
   // --- internal wiring used by <Otp.Input> ---
+  /** The `id` for the slot at `index`. Slot `0` takes the root's `id` so a `<label>` can target it. */
+  getInputId: (index: number) => string;
+  /**
+   * The accessible name the first slot inherits from the root, or `undefined` when the root
+   * carries no name of its own and the slot is left to a native `<label>`.
+   */
+  firstInputLabel: FirstInputLabel | undefined;
   /** Register/unregister a slot input's element by index. */
   registerInput: (index: number, element: HTMLInputElement | null) => void;
   /** Propose a new full value; it is sanitized and clamped before commit. */
diff --git a/packages/headless/src/primitives/otp/otp-input.tsx b/packages/headless/src/primitives/otp/otp-input.tsx
index 36e6b1441e0..7d3687a820b 100644
--- a/packages/headless/src/primitives/otp/otp-input.tsx
+++ b/packages/headless/src/primitives/otp/otp-input.tsx
@@ -17,12 +17,15 @@ export const OtpInput = React.forwardRef<HTMLInputElement, OtpInputProps>(functi
     value,
     length,
     disabled,
+    required,
     pattern,
     mask,
     activeIndex,
     setValue,
     queueFocus,
     focus,
+    getInputId,
+    firstInputLabel,
     registerInput,
     onSlotFocus,
     onSlotBlur,
@@ -40,9 +43,14 @@ export const OtpInput = React.forwardRef<HTMLInputElement, OtpInputProps>(functi
   // when the field is unfocused, so Tab enters and leaves the group once.
   const tabStop = activeIndex ?? Math.min(value.length, length - 1);
 
+  // The first slot answers to the field's own name; the rest are positional.
+  const labelProps = index === 0 ? (firstInputLabel ?? {}) : { 'aria-label': `Character ${index + 1} of ${length}` };
+
   const state = { active: activeIndex === index, filled: char !== '', disabled };
 
   const defaultProps: Record<string, unknown> = {
+    id: getInputId(index),
+    ...labelProps,
     value: char,
     type: mask ? 'password' : 'text',
     inputMode: inputModeForPattern(pattern),
@@ -56,7 +64,9 @@ export const OtpInput = React.forwardRef<HTMLInputElement, OtpInputProps>(functi
     maxLength: index === 0 ? length : 1,
     tabIndex: tabStop === index ? 0 : -1,
     disabled,
-    'aria-label': `Character ${index + 1} of ${length}`,
+    // Constraint validation rides on the visible slots: the hidden input is `readOnly`,
+    // which bars it from validation entirely.
+    required,
     onMouseDown: (event: React.MouseEvent<HTMLInputElement>) => {
       if (disabled) {
         return;
diff --git a/packages/headless/src/primitives/otp/otp-root.tsx b/packages/headless/src/primitives/otp/otp-root.tsx
index f303c2a7102..c82514c8c89 100644
--- a/packages/headless/src/primitives/otp/otp-root.tsx
+++ b/packages/headless/src/primitives/otp/otp-root.tsx
@@ -1,10 +1,10 @@
 'use client';
 
-import { type CSSProperties, type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { type CSSProperties, type ReactNode, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../../hooks/use-controllable-state';
 import { type ComponentProps, mergeProps, useRender } from '../../utils';
-import { OtpContext, type OtpContextValue, type OtpSlot } from './otp-context';
+import { type FirstInputLabel, OtpContext, type OtpContextValue, type OtpSlot } from './otp-context';
 import { inputModeForPattern, type OtpPattern, sanitize } from './otp-utils';
 
 export interface OtpProps extends Omit<ComponentProps<'div'>, 'value' | 'defaultValue' | 'onChange'> {
@@ -29,6 +29,13 @@ export interface OtpProps extends Omit<ComponentProps<'div'>, 'value' | 'default
   name?: string;
   /** Disable every slot and the picker. @default false */
   disabled?: boolean;
+  /** Require every slot to be filled before the enclosing form submits. @default false */
+  required?: boolean;
+  /**
+   * Identifies the field for a `<label>`. Applied to the first slot rather than this
+   * element, since a `role="group"` is not labelable. Generated when omitted.
+   */
+  id?: string;
   children: ReactNode;
 }
 
@@ -58,10 +65,31 @@ export function OtpRoot(props: OtpProps) {
     mask = false,
     name,
     disabled = false,
+    required = false,
+    id: idProp,
     children,
     ...otherProps
   } = props;
 
+  const generatedId = useId();
+  const id = idProp ?? `otp-${generatedId}`;
+  const getInputId = useCallback((index: number) => (index === 0 ? id : `${id}-${index + 1}`), [id]);
+
+  // The first slot is what a `<label>` targets and where focus lands, so it takes the field's
+  // name instead of its positional one; otherwise its accessible name would contradict the
+  // visible label. With no name here the slot is left to a native `<label>`.
+  const ariaLabel = otherProps['aria-label'];
+  const ariaLabelledBy = otherProps['aria-labelledby'];
+  const firstInputLabel = useMemo<FirstInputLabel | undefined>(() => {
+    if (ariaLabelledBy) {
+      return { 'aria-labelledby': ariaLabelledBy };
+    }
+    if (ariaLabel) {
+      return { 'aria-label': ariaLabel };
+    }
+    return undefined;
+  }, [ariaLabel, ariaLabelledBy]);
+
   const [rawValue, setRawValue] = useControllableState(valueProp, defaultValue, onValueChange);
   // Never let out-of-range or disallowed characters reach the slots, even from a
   // controlled/default value the consumer passes in.
@@ -140,6 +168,7 @@ export function OtpRoot(props: OtpProps) {
       value,
       length,
       disabled,
+      required,
       complete,
       pattern,
       mask,
@@ -147,6 +176,8 @@ export function OtpRoot(props: OtpProps) {
       activeIndex,
       clear,
       focus,
+      getInputId,
+      firstInputLabel,
       registerInput,
       setValue,
       queueFocus,
@@ -157,6 +188,7 @@ export function OtpRoot(props: OtpProps) {
       value,
       length,
       disabled,
+      required,
       complete,
       pattern,
       mask,
@@ -164,6 +196,8 @@ export function OtpRoot(props: OtpProps) {
       activeIndex,
       clear,
       focus,
+      getInputId,
+      firstInputLabel,
       registerInput,
       setValue,
       queueFocus,
@@ -185,6 +219,7 @@ export function OtpRoot(props: OtpProps) {
             name={name}
             value={value}
             readOnly
+            disabled={disabled}
             aria-hidden='true'
             tabIndex={-1}
             autoComplete='one-time-code'
diff --git a/packages/headless/src/primitives/otp/otp.test.tsx b/packages/headless/src/primitives/otp/otp.test.tsx
index cb1ffe8f486..f6bc115d5af 100644
--- a/packages/headless/src/primitives/otp/otp.test.tsx
+++ b/packages/headless/src/primitives/otp/otp.test.tsx
@@ -517,6 +517,107 @@ describe('Otp', () => {
     });
   });
 
+  describe('form integration', () => {
+    it('marks every slot required so a partial code fails validation', () => {
+      render(
+        <Harness
+          required
+          name='code'
+          defaultValue='12'
+        />,
+      );
+      expect(inputs().every(input => input.required)).toBe(true);
+      expect(inputs()[2].checkValidity()).toBe(false);
+      expect(inputs()[0].checkValidity()).toBe(true);
+    });
+
+    it('does not require slots by default', () => {
+      render(<Harness />);
+      expect(inputs().some(input => input.required)).toBe(false);
+    });
+
+    it('disables the hidden input so a disabled field submits nothing', () => {
+      render(
+        <Harness
+          disabled
+          name='code'
+          defaultValue='1234'
+        />,
+      );
+      const hidden = document.querySelector<HTMLInputElement>('input[name="code"]');
+      expect(hidden).toBeDisabled();
+
+      const form = document.createElement('form');
+      form.append(hidden as Node);
+      expect(Array.from(new FormData(form).keys())).toEqual([]);
+    });
+
+    it('submits the hidden input when enabled', () => {
+      render(
+        <Harness
+          name='code'
+          defaultValue='1234'
+        />,
+      );
+      const hidden = document.querySelector<HTMLInputElement>('input[name="code"]');
+      expect(hidden).not.toBeDisabled();
+
+      const form = document.createElement('form');
+      form.append(hidden as Node);
+      expect(new FormData(form).get('code')).toBe('1234');
+    });
+  });
+
+  describe('labelling', () => {
+    it('puts the root id on the first slot and derives the rest from it', () => {
+      render(<Harness id='code' />);
+      expect(inputs().map(input => input.id)).toEqual(['code', 'code-2', 'code-3', 'code-4']);
+      expect(document.querySelector('[data-testid="otp-root"]')).not.toHaveAttribute('id');
+    });
+
+    it('generates slot ids when no id is given', () => {
+      render(<Harness />);
+      expect(inputs().every(input => input.id !== '')).toBe(true);
+      expect(new Set(inputs().map(input => input.id)).size).toBe(4);
+    });
+
+    it('names the first slot after a native label targeting it', () => {
+      render(
+        <>
+          <label htmlFor='code'>Verification code</label>
+          <Harness id='code' />
+        </>,
+      );
+      expect(inputs()[0]).not.toHaveAttribute('aria-label');
+      expect(screen.getByLabelText('Verification code')).toBe(inputs()[0]);
+    });
+
+    it('passes the root aria-labelledby down to the first slot', () => {
+      render(
+        <>
+          <span id='code-label'>Verification code</span>
+          <Harness aria-labelledby='code-label' />
+        </>,
+      );
+      expect(inputs()[0]).toHaveAttribute('aria-labelledby', 'code-label');
+      expect(inputs()[0]).not.toHaveAttribute('aria-label');
+    });
+
+    it('passes the root aria-label down to the first slot', () => {
+      render(<Harness aria-label='Verification code' />);
+      expect(inputs()[0]).toHaveAttribute('aria-label', 'Verification code');
+    });
+
+    it('labels the remaining slots positionally', () => {
+      render(<Harness aria-label='Verification code' />);
+      expect(
+        inputs()
+          .slice(1)
+          .map(input => input.getAttribute('aria-label')),
+      ).toEqual(['Character 2 of 4', 'Character 3 of 4', 'Character 4 of 4']);
+    });
+  });
+
   describe('accessibility', () => {
     it('has no axe violations', async () => {
       const { container } = render(
diff --git a/packages/swingset/src/stories/otp.component.mdx b/packages/swingset/src/stories/otp.component.mdx
index 7602e48afa2..0176e839b87 100644
--- a/packages/swingset/src/stories/otp.component.mdx
+++ b/packages/swingset/src/stories/otp.component.mdx
@@ -56,10 +56,13 @@ const [code, setCode] = useState('');
 />;
 ```
 
-Inside a `Field.Root`, the field's `disabled` and `invalid` flow into the boxes, and the label and messages are associated with the group:
+Inside a `Field.Root`, the field's `disabled`, `required`, and `invalid` flow into the boxes, and the messages are associated with the group. `Field.Label` targets the first box, so clicking it focuses the code — drop `aria-label` and let the label name the field:
 
 ```tsx
-<Field.Root invalid={Boolean(error)}>
+<Field.Root
+  required
+  invalid={Boolean(error)}
+>
   <Field.Label>Verification code</Field.Label>
   <Otp name='code' />
   {error ? <Field.Error>{error}</Field.Error> : <Field.Description>Didn’t receive a code? Resend</Field.Description>}
@@ -72,6 +75,13 @@ Inside a `Field.Root`, the field's `disabled` and `invalid` flow into the boxes,
 
 ## Examples
 
+### In a Field
+
+<Story
+  name='WithField'
+  storyModule={OtpStories}
+/>
+
 ### Success
 
 <Story
diff --git a/packages/swingset/src/stories/otp.component.stories.tsx b/packages/swingset/src/stories/otp.component.stories.tsx
index 209ec623262..e02ef605eab 100644
--- a/packages/swingset/src/stories/otp.component.stories.tsx
+++ b/packages/swingset/src/stories/otp.component.stories.tsx
@@ -41,6 +41,19 @@ export function Default(props: Record<string, unknown>) {
   );
 }
 
+export function WithField() {
+  return (
+    <Field.Root
+      required
+      style={stackStyles}
+    >
+      <Field.Label>Verification code</Field.Label>
+      <Otp name='code' />
+      <Field.Description>Enter the code we sent to your device.</Field.Description>
+    </Field.Root>
+  );
+}
+
 export function Success() {
   return (
     <Field.Root style={stackStyles}>
diff --git a/packages/swingset/src/stories/otp.mdx b/packages/swingset/src/stories/otp.mdx
index 3a1c5108c6e..5917b4435e1 100644
--- a/packages/swingset/src/stories/otp.mdx
+++ b/packages/swingset/src/stories/otp.mdx
@@ -111,17 +111,19 @@ inside `Otp.Root`.
 
 ### `Otp.Root`
 
-| Prop            | Type                                     | Default      | Description                                         |
-| --------------- | ---------------------------------------- | ------------ | --------------------------------------------------- |
-| `length`        | `number`                                 | — (required) | Number of slots (characters) in the code            |
-| `value`         | `string`                                 | —            | Controlled value                                    |
-| `defaultValue`  | `string`                                 | `''`         | Initial value (uncontrolled)                        |
-| `onValueChange` | `(value: string) => void`                | —            | Called with the full value on every change          |
-| `onComplete`    | `(value: string) => void`                | —            | Called once every slot is filled                    |
-| `pattern`       | `'numeric' \| 'alpha' \| 'alphanumeric'` | `'numeric'`  | Allowed characters; others are stripped             |
-| `mask`          | `boolean`                                | `false`      | Render slots as password inputs                     |
-| `name`          | `string`                                 | —            | Submit the value via a hidden input under this name |
-| `disabled`      | `boolean`                                | `false`      | Disable every slot                                  |
+| Prop            | Type                                     | Default      | Description                                            |
+| --------------- | ---------------------------------------- | ------------ | ------------------------------------------------------ |
+| `length`        | `number`                                 | — (required) | Number of slots (characters) in the code               |
+| `value`         | `string`                                 | —            | Controlled value                                       |
+| `defaultValue`  | `string`                                 | `''`         | Initial value (uncontrolled)                           |
+| `onValueChange` | `(value: string) => void`                | —            | Called with the full value on every change             |
+| `onComplete`    | `(value: string) => void`                | —            | Called once every slot is filled                       |
+| `pattern`       | `'numeric' \| 'alpha' \| 'alphanumeric'` | `'numeric'`  | Allowed characters; others are stripped                |
+| `mask`          | `boolean`                                | `false`      | Render slots as password inputs                        |
+| `name`          | `string`                                 | —            | Submit the value via a hidden input under this name    |
+| `disabled`      | `boolean`                                | `false`      | Disable every slot and the hidden input                |
+| `required`      | `boolean`                                | `false`      | Require every slot to be filled before submitting      |
+| `id`            | `string`                                 | generated    | Applied to the first slot so a `<label>` can target it |
 
 ### `Otp.Input`
 
@@ -159,7 +161,12 @@ Each part emits `data-*` attributes you can target with any CSS solution:
 ```
 
 `Otp.Root` is a `role="group"`; give it an `aria-label` (or `aria-labelledby`) describing the code.
-Each `Otp.Input` gets a default `aria-label` of `"Character N of M"` (overridable), and the slots use
-a roving tab index so `Tab` enters the group once and leaves in one step. When `name` is set, the
-hidden form input is `aria-hidden` and out of the tab order. Arrow keys follow reading order — under
-`dir="rtl"`, `ArrowLeft`/`ArrowRight` are swapped.
+Because a group is not labelable, `Otp.Root`'s `id` lands on the _first_ slot (the rest take
+`${id}-2`, `${id}-3`, …), so a `<label htmlFor>` targets a real control and clicking it focuses the
+code. That first slot inherits the group's name rather than a positional one — a `"Character 1 of N"`
+there would contradict the visible label — while the remaining slots get a default `aria-label` of
+`"Character N of M"` (overridable). The slots use a roving tab index so `Tab` enters the group once
+and leaves in one step. `required` is applied to each slot, not the hidden input, which is `readOnly`
+and therefore barred from constraint validation. When `name` is set, the hidden form input is
+`aria-hidden`, out of the tab order, and disabled alongside the field. Arrow keys follow reading
+order — under `dir="rtl"`, `ArrowLeft`/`ArrowRight` are swapped.
diff --git a/packages/ui/src/mosaic/components/otp/otp.test.tsx b/packages/ui/src/mosaic/components/otp/otp.test.tsx
index 510e6e39fce..b2a8fd1464c 100644
--- a/packages/ui/src/mosaic/components/otp/otp.test.tsx
+++ b/packages/ui/src/mosaic/components/otp/otp.test.tsx
@@ -141,6 +141,54 @@ describe('Mosaic Otp', () => {
     expect(group).toHaveAccessibleDescription('Check your email.');
   });
 
+  it('points the Field label at the first slot so clicking it focuses the code', async () => {
+    render(
+      <Field.Root>
+        <Field.Label>Verification code</Field.Label>
+        <Otp length={3} />
+      </Field.Root>,
+    );
+
+    const label = screen.getByText('Verification code');
+    const first = slots()[0];
+    expect(first.id).not.toBe('');
+    expect(label).toHaveAttribute('for', first.id);
+    expect(first).toHaveAccessibleName('Verification code');
+    expect(slots()[1]).toHaveAccessibleName('Character 2 of 3');
+
+    await userEvent.click(label);
+    expect(first).toHaveFocus();
+  });
+
+  it('takes required from an enclosing Field and enforces it on every slot', () => {
+    render(
+      <Field.Root required>
+        <Field.Label>Verification code</Field.Label>
+        <Otp
+          length={3}
+          name='code'
+        />
+      </Field.Root>,
+    );
+
+    expect(slots().every(slot => (slot as HTMLInputElement).required)).toBe(true);
+  });
+
+  it('does not submit the value when an enclosing Field is disabled', () => {
+    render(
+      <Field.Root disabled>
+        <Otp
+          length={3}
+          name='code'
+          defaultValue='123'
+          aria-label='Code'
+        />
+      </Field.Root>,
+    );
+
+    expect(document.querySelector('input[name="code"]')).toBeDisabled();
+  });
+
   it('submits the combined value under the given name', () => {
     render(
       <Otp
diff --git a/packages/ui/src/mosaic/components/otp/otp.tsx b/packages/ui/src/mosaic/components/otp/otp.tsx
index ddd8dfed08e..02b82c4b412 100644
--- a/packages/ui/src/mosaic/components/otp/otp.tsx
+++ b/packages/ui/src/mosaic/components/otp/otp.tsx
@@ -50,18 +50,23 @@ export function Otp({
   length = 6,
   status: statusProp,
   disabled: disabledProp,
+  required: requiredProp,
+  id,
   'aria-invalid': ariaInvalidProp,
   'aria-labelledby': ariaLabelledBy,
   'aria-describedby': ariaDescribedBy,
   ...rest
 }: OtpProps): React.ReactElement {
   const fieldProps = useOptionalFieldControlProps({
+    id,
     disabled: disabledProp,
+    required: requiredProp,
     ariaInvalid: ariaInvalidProp,
     ariaLabelledBy,
     ariaDescribedBy,
   });
   const disabled = fieldProps?.disabled ?? disabledProp ?? false;
+  const required = fieldProps?.required ?? requiredProp;
   const ariaInvalid = fieldProps?.['aria-invalid'] ?? ariaInvalidProp;
   const status = statusProp ?? (ariaInvalid === true || ariaInvalid === 'true' ? 'error' : 'neutral');
 
@@ -70,6 +75,8 @@ export function Otp({
       {...rest}
       length={length}
       disabled={disabled}
+      required={required}
+      id={fieldProps?.id ?? id}
       {...mergeStyleProps(themeProps('otp', { status, disabled }), stylex.props(reset.base, styles.root))}
       aria-labelledby={fieldProps?.['aria-labelledby'] ?? ariaLabelledBy}
       aria-describedby={fieldProps?.['aria-describedby'] ?? ariaDescribedBy}