From 21d11b09953c930f5de01dd710b765cf12db0e53 Mon Sep 17 00:00:00 2001 From: Alex Carpenter Date: Fri, 8 May 2026 16:13:13 -0400 Subject: [PATCH 1/2] chore: Add docs for appearance options elevation --- .../guides/customizing-clerk/appearance-prop/options.mdx | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/guides/customizing-clerk/appearance-prop/options.mdx b/docs/guides/customizing-clerk/appearance-prop/options.mdx index a6b23a12e9..78ba244260 100644 --- a/docs/guides/customizing-clerk/appearance-prop/options.mdx +++ b/docs/guides/customizing-clerk/appearance-prop/options.mdx @@ -6,7 +6,7 @@ sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, tanstack- {/* JS file: https://github.com/clerk/javascript/blob/main/packages/types/src/appearance.ts#L538 */} -The `options` property can be used to change the layout of the [``](/docs/reference/components/authentication/sign-in) and [``](/docs/reference/components/authentication/sign-up) components, as well as set important links to your support, terms, and privacy pages. +The `options` property can be used to change the layout and behavior of Clerk's prebuilt components, as well as set important links to your support, terms, and privacy pages. ## Properties @@ -18,6 +18,13 @@ The `options` property can be used to change the layout of the [``](/do --- + - `elevation` + - `'raised' | 'flush'` + + Controls the visual elevation of card-based components. `'raised'` renders the card with its border, box-shadow, border-radius, and padding. `'flush'` removes the card border, box-shadow, border-radius, outer padding, and footer background so the component sits flat against its container. Applies to page-mounted card-based components such as [``](/docs/reference/components/authentication/sign-in), [``](/docs/reference/components/authentication/sign-up), [``](/docs/reference/components/authentication/waitlist), [``](/docs/reference/components/organization/create-organization), and [``](/docs/reference/components/organization/organization-list). Does not affect profile components ([``](/docs/reference/components/user/user-profile), [``](/docs/reference/components/organization/organization-profile)) or popover components ([``](/docs/reference/components/user/user-button), [``](/docs/reference/components/organization/organization-switcher)), which always render as raised. When a component is opened as a modal, it always renders as raised regardless of this setting. Defaults to `'raised'`. + + --- + - `helpPageUrl` - `string` From e82ab29836f2bf506b9883723d0cb3479f725bf7 Mon Sep 17 00:00:00 2001 From: Michael Novotny Date: Thu, 21 May 2026 16:06:28 -0500 Subject: [PATCH 2/2] docs: Refine elevation option and fix appearance source links - Add session task components to the elevation "applies to" list - Broaden the options.mdx meta description to match the body - Point the appearance docs' JS file comments at packages/ui/src/internal/appearance.ts (the prior packages/types path 404s); drop fragile line anchors - Alphabetize animations before autoFocus Co-Authored-By: Claude Opus 4.7 (1M context) --- .../customizing-clerk/appearance-prop/captcha.mdx | 2 +- .../customizing-clerk/appearance-prop/options.mdx | 14 +++++++------- .../customizing-clerk/appearance-prop/overview.mdx | 2 +- .../appearance-prop/variables.mdx | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/guides/customizing-clerk/appearance-prop/captcha.mdx b/docs/guides/customizing-clerk/appearance-prop/captcha.mdx index 436cbd4821..35b65e1033 100644 --- a/docs/guides/customizing-clerk/appearance-prop/captcha.mdx +++ b/docs/guides/customizing-clerk/appearance-prop/captcha.mdx @@ -4,7 +4,7 @@ description: Utilize Clerk's captcha prop in order to change the appearance of t sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, tanstack-react-start, vue, js-frontend, fastify, expressjs, go, ruby --- -{/* JS file: https://github.com/clerk/javascript/blob/main/packages/types/src/appearance.ts#L538 */} +{/* JS file: https://github.com/clerk/javascript/blob/main/packages/ui/src/internal/appearance.ts */} The `captcha` property can be used to change the appearance of the CAPTCHA widget. diff --git a/docs/guides/customizing-clerk/appearance-prop/options.mdx b/docs/guides/customizing-clerk/appearance-prop/options.mdx index 9d41da609c..b70ad7891c 100644 --- a/docs/guides/customizing-clerk/appearance-prop/options.mdx +++ b/docs/guides/customizing-clerk/appearance-prop/options.mdx @@ -1,34 +1,34 @@ --- title: '`Options` prop' -description: Utilize Clerk's options prop in order to change the layout of the and components, as well as set important links to your support, terms and privacy pages. +description: Utilize Clerk's options prop in order to change the layout and behavior of Clerk's prebuilt components, as well as set important links to your support, terms, and privacy pages. sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, tanstack-react-start, vue, js-frontend, fastify, expressjs, go, ruby --- -{/* JS file: https://github.com/clerk/javascript/blob/main/packages/types/src/appearance.ts#L538 */} +{/* JS file: https://github.com/clerk/javascript/blob/main/packages/ui/src/internal/appearance.ts */} The `options` property can be used to change the layout and behavior of Clerk's prebuilt components, as well as set important links to your support, terms, and privacy pages. ## Properties - - `autoFocus` + - `animations` - `boolean` - Whether inputs automatically receive focus when a component is mounted. Set to `false` to prevent components from auto-focusing any input fields. Defaults to `true`. + Whether to enable animations inside the components. Defaults to `true`. --- - - `animations` + - `autoFocus` - `boolean` - Whether to enable animations inside the components. Defaults to `true`. + Whether inputs automatically receive focus when a component is mounted. Set to `false` to prevent components from auto-focusing any input fields. Defaults to `true`. --- - `elevation` - `'raised' | 'flush'` - Controls the visual elevation of card-based components. `'raised'` renders the card with its border, box-shadow, border-radius, and padding. `'flush'` removes the card border, box-shadow, border-radius, outer padding, and footer background so the component sits flat against its container. Applies to page-mounted card-based components such as [``](/docs/reference/components/authentication/sign-in), [``](/docs/reference/components/authentication/sign-up), [``](/docs/reference/components/authentication/waitlist), [``](/docs/reference/components/organization/create-organization), and [``](/docs/reference/components/organization/organization-list). Does not affect profile components ([``](/docs/reference/components/user/user-profile), [``](/docs/reference/components/organization/organization-profile)) or popover components ([``](/docs/reference/components/user/user-button), [``](/docs/reference/components/organization/organization-switcher)), which always render as raised. When a component is opened as a modal, it always renders as raised regardless of this setting. Defaults to `'raised'`. + Controls the visual elevation of card-based components. `'raised'` renders the card with its border, box-shadow, border-radius, and padding. `'flush'` removes the card border, box-shadow, border-radius, outer padding, and footer background so the component sits flat against its container. Applies to page-mounted card-based components such as [``](/docs/reference/components/authentication/sign-in), [``](/docs/reference/components/authentication/sign-up), [``](/docs/reference/components/authentication/waitlist), [``](/docs/reference/components/organization/create-organization), [``](/docs/reference/components/organization/organization-list), and session task components ([``](/docs/reference/components/authentication/task-choose-organization), [``](/docs/reference/components/authentication/task-reset-password), [``](/docs/reference/components/authentication/task-setup-mfa)). Does not affect profile components ([``](/docs/reference/components/user/user-profile), [``](/docs/reference/components/organization/organization-profile)) or popover components ([``](/docs/reference/components/user/user-button), [``](/docs/reference/components/organization/organization-switcher)), which always render as raised. When a component is opened as a modal, it always renders as raised regardless of this setting. Defaults to `'raised'`. --- diff --git a/docs/guides/customizing-clerk/appearance-prop/overview.mdx b/docs/guides/customizing-clerk/appearance-prop/overview.mdx index 4c3d92dc3a..f5021b0854 100644 --- a/docs/guides/customizing-clerk/appearance-prop/overview.mdx +++ b/docs/guides/customizing-clerk/appearance-prop/overview.mdx @@ -4,7 +4,7 @@ description: Utilize Clerk's appearance property in order to share styles across sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, tanstack-react-start, vue, js-frontend, fastify, expressjs, go, ruby --- -{/* JS file: https://github.com/clerk/javascript/blob/main/packages/types/src/appearance.ts#L619 */} +{/* JS file: https://github.com/clerk/javascript/blob/main/packages/ui/src/internal/appearance.ts */} Customizing the appearance of Clerk components is a powerful way to make your application look and feel unique. Clerk provides a way to customize the appearance of its components using the `appearance` prop. diff --git a/docs/guides/customizing-clerk/appearance-prop/variables.mdx b/docs/guides/customizing-clerk/appearance-prop/variables.mdx index a3810d52b2..6af40f935c 100644 --- a/docs/guides/customizing-clerk/appearance-prop/variables.mdx +++ b/docs/guides/customizing-clerk/appearance-prop/variables.mdx @@ -4,7 +4,7 @@ description: Utilize Clerk's variables property in order to adjust the general s sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, tanstack-react-start, vue, js-frontend, fastify, expressjs, go, ruby --- -{/* JS file: https://github.com/clerk/javascript/blob/main/packages/types/src/appearance.ts#L399 */} +{/* JS file: https://github.com/clerk/javascript/blob/main/packages/ui/src/internal/appearance.ts */} The `variables` property is used to adjust the general styles of the component's base theme, like colors, backgrounds, and typography.