From f15837ccac62ad13837406d4ba830f72f17f72fd Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Mon, 11 May 2026 16:34:09 -0400
Subject: [PATCH 1/2] feat(ui): Add appearance option to disable autofocus

---
 .../src/components/UserProfile/MfaBackupCodeCreateForm.tsx | 5 +++--
 packages/ui/src/customizables/parseAppearance.ts           | 1 +
 packages/ui/src/elements/CodeControl.tsx                   | 5 +++--
 packages/ui/src/elements/FieldControl.tsx                  | 3 +++
 packages/ui/src/elements/SuccessPage.tsx                   | 5 +++--
 packages/ui/src/elements/TagInput.tsx                      | 6 ++++--
 packages/ui/src/internal/appearance.ts                     | 7 +++++++
 7 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/packages/ui/src/components/UserProfile/MfaBackupCodeCreateForm.tsx b/packages/ui/src/components/UserProfile/MfaBackupCodeCreateForm.tsx
index ed4dc9c668b..e542a62ab2a 100644
--- a/packages/ui/src/components/UserProfile/MfaBackupCodeCreateForm.tsx
+++ b/packages/ui/src/components/UserProfile/MfaBackupCodeCreateForm.tsx
@@ -10,7 +10,7 @@ import { FormContainer } from '@/ui/elements/FormContainer';
 import { FullHeightLoader } from '@/ui/elements/FullHeightLoader';
 import { handleError } from '@/ui/utils/errorHandler';
 
-import { Button, descriptors, localizationKeys, Text } from '../../customizables';
+import { Button, descriptors, localizationKeys, Text, useAppearance } from '../../customizables';
 import { MfaBackupCodeList } from './MfaBackupCodeList';
 
 type MfaBackupCodeCreateFormProps = FormProps;
@@ -18,6 +18,7 @@ export const MfaBackupCodeCreateForm = withCardStateProvider((props: MfaBackupCo
   const { onSuccess, onReset } = props;
   const { user } = useUser();
   const card = useCardState();
+  const { autoFocus: optionAutoFocus } = useAppearance().parsedOptions;
   const createBackupCode = useReverification(() => user?.createBackupCode());
   const [backupCode, setBackupCode] = React.useState<BackupCodeResource | undefined>(undefined);
 
@@ -56,7 +57,7 @@ export const MfaBackupCodeCreateForm = withCardStateProvider((props: MfaBackupCo
 
           <FormButtonContainer>
             <Button
-              autoFocus
+              autoFocus={optionAutoFocus}
               onClick={onSuccess}
               localizationKey={localizationKeys('userProfile.formButtonPrimary__finish')}
               elementDescriptor={descriptors.formButtonPrimary}
diff --git a/packages/ui/src/customizables/parseAppearance.ts b/packages/ui/src/customizables/parseAppearance.ts
index a61b883191f..08aa4ad17b0 100644
--- a/packages/ui/src/customizables/parseAppearance.ts
+++ b/packages/ui/src/customizables/parseAppearance.ts
@@ -51,6 +51,7 @@ const defaultOptions: ParsedOptions = {
   shimmer: true,
   animations: true,
   unsafe_disableDevelopmentModeWarnings: false,
+  autoFocus: true,
 };
 
 const defaultCaptchaOptions: ParsedCaptcha = {
diff --git a/packages/ui/src/elements/CodeControl.tsx b/packages/ui/src/elements/CodeControl.tsx
index d04c2c84327..f4896080a9b 100644
--- a/packages/ui/src/elements/CodeControl.tsx
+++ b/packages/ui/src/elements/CodeControl.tsx
@@ -5,7 +5,7 @@ import type { PropsWithChildren } from 'react';
 import React, { useCallback } from 'react';
 
 import type { LocalizationKey } from '../customizables';
-import { Box, descriptors, Flex, OTPInputSegment } from '../customizables';
+import { Box, descriptors, Flex, OTPInputSegment, useAppearance } from '../customizables';
 import { useCardState } from '../elements/contexts';
 import { useLoadingStatus } from '../hooks';
 import type { PropsOfComponent } from '../styledSystem';
@@ -166,6 +166,7 @@ export const OTPResendButton = () => {
 export const OTPCodeControl = () => {
   const [disabled, setDisabled] = React.useState(false);
   const { otpControl, isLoading, isDisabled } = useOTPInputContext();
+  const { autoFocus: optionAutoFocus } = useAppearance().parsedOptions;
   const { feedback, values, setValues, feedbackType, length } = otpControl.otpInputProps;
 
   React.useEffect(() => {
@@ -180,7 +181,7 @@ export const OTPCodeControl = () => {
       sx={{ position: 'relative' }}
     >
       <OTPInput
-        autoFocus // eslint-disable-line jsx-a11y/no-autofocus
+        autoFocus={optionAutoFocus} // eslint-disable-line jsx-a11y/no-autofocus
         aria-label='Enter verification code'
         aria-required
         maxLength={length}
diff --git a/packages/ui/src/elements/FieldControl.tsx b/packages/ui/src/elements/FieldControl.tsx
index 94995209229..b53de5fda3f 100644
--- a/packages/ui/src/elements/FieldControl.tsx
+++ b/packages/ui/src/elements/FieldControl.tsx
@@ -13,6 +13,7 @@ import {
   Link,
   localizationKeys,
   Text,
+  useAppearance,
   useLocalizations,
 } from '../customizables';
 import type { ElementDescriptor, ElementId } from '../customizables/elementDescriptors';
@@ -33,6 +34,7 @@ type FormControlProps = Omit<PropsOfComponent<typeof Input>, 'label' | 'placehol
 
 const Root = (props: PropsWithChildren<FormControlProps>) => {
   const card = useCardState();
+  const { autoFocus: optionAutoFocus } = useAppearance().parsedOptions;
   const { children, isDisabled: isDisabledProp, ...restProps } = props;
 
   const isDisabled = isDisabledProp || card.isLoading;
@@ -40,6 +42,7 @@ const Root = (props: PropsWithChildren<FormControlProps>) => {
   const ctxProps = {
     ...restProps,
     isDisabled,
+    autoFocus: optionAutoFocus && restProps.autoFocus,
   };
 
   return <FormFieldContextProvider {...ctxProps}>{children}</FormFieldContextProvider>;
diff --git a/packages/ui/src/elements/SuccessPage.tsx b/packages/ui/src/elements/SuccessPage.tsx
index b8b0680b7c7..fc50e20c761 100644
--- a/packages/ui/src/elements/SuccessPage.tsx
+++ b/packages/ui/src/elements/SuccessPage.tsx
@@ -1,7 +1,7 @@
 import React from 'react';
 
 import type { Flex } from '../customizables';
-import { Button, Col, descriptors, Text } from '../customizables';
+import { Button, Col, descriptors, Text, useAppearance } from '../customizables';
 import { useNavigateToFlowStart } from '../hooks';
 import type { LocalizationKey } from '../localization';
 import { localizationKeys } from '../localization';
@@ -23,6 +23,7 @@ type SuccessPageProps = Omit<PropsOfComponent<typeof Flex>, 'headerTitle' | 'tit
 export const SuccessPage = (props: SuccessPageProps) => {
   const { text, title, subtitle, finishLabel, onFinish, contents, finishButtonProps, headerBadgeText, ...rest } = props;
   const { navigateToFlowStart } = useNavigateToFlowStart();
+  const { autoFocus: optionAutoFocus } = useAppearance().parsedOptions;
 
   return (
     <Col
@@ -63,7 +64,7 @@ export const SuccessPage = (props: SuccessPageProps) => {
       {contents}
       <FormButtonContainer>
         <Button
-          autoFocus
+          autoFocus={optionAutoFocus}
           //Do we need a separate key here?
           localizationKey={finishLabel || localizationKeys('userProfile.formButtonPrimary__finish')}
           elementDescriptor={descriptors.formButtonPrimary}
diff --git a/packages/ui/src/elements/TagInput.tsx b/packages/ui/src/elements/TagInput.tsx
index 2323ca387ac..17a02456e03 100644
--- a/packages/ui/src/elements/TagInput.tsx
+++ b/packages/ui/src/elements/TagInput.tsx
@@ -1,7 +1,7 @@
 import React from 'react';
 
 import type { LocalizationKey } from '../customizables';
-import { descriptors, Flex, Icon, Input, Text, useLocalizations } from '../customizables';
+import { descriptors, Flex, Icon, Input, Text, useAppearance, useLocalizations } from '../customizables';
 import { Plus } from '../icons';
 import type { PropsOfComponent } from '../styledSystem';
 import { common } from '../styledSystem';
@@ -21,16 +21,18 @@ type TagInputProps = Pick<PropsOfComponent<typeof Flex>, 'sx'> & {
 
 export const TagInput = (props: TagInputProps) => {
   const { t } = useLocalizations();
+  const { autoFocus: optionAutoFocus } = useAppearance().parsedOptions;
   const {
     sx,
     placeholder,
     validate = () => true,
     value: valueProp,
     onChange: onChangeProp,
-    autoFocus,
+    autoFocus: autoFocusProp,
     validateUnsubmittedEmail = () => null,
     ...rest
   } = props;
+  const autoFocus = optionAutoFocus && autoFocusProp;
   const tags = valueProp.split(',').map(sanitize).filter(Boolean);
   const tagsSet = new Set(tags);
   const keyReleasedRef = React.useRef(true);
diff --git a/packages/ui/src/internal/appearance.ts b/packages/ui/src/internal/appearance.ts
index 0c4f546d50c..c062ad06458 100644
--- a/packages/ui/src/internal/appearance.ts
+++ b/packages/ui/src/internal/appearance.ts
@@ -987,6 +987,13 @@ export type Options = {
    * @default false
    */
   unsafe_disableDevelopmentModeWarnings?: boolean;
+  /**
+   * Controls whether inputs will automatically receive focus when a component is mounted.
+   * Set to false to prevent the components from auto-focusing any input fields.
+   *
+   * @default true
+   */
+  autoFocus?: boolean;
 };
 
 export type CaptchaAppearanceOptions = {

From 6dd8ff206638ad36f6af6163dc2949e5b5786c16 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 12 May 2026 09:01:50 -0400
Subject: [PATCH 2/2] Create lazy-hawk-old-fish.md

---
 .changeset/lazy-hawk-old-fish.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/lazy-hawk-old-fish.md

diff --git a/.changeset/lazy-hawk-old-fish.md b/.changeset/lazy-hawk-old-fish.md
new file mode 100644
index 00000000000..7ebaaf722de
--- /dev/null
+++ b/.changeset/lazy-hawk-old-fish.md
@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+Add `autoFocus` appearance option to disable automatic input focusing