clerk · alexcarpenter · Oct 9, 2025 · Oct 17, 2025 · Oct 20, 2025 · Oct 20, 2025
@@ -338,8 +338,51 @@ The `search` frontmatter field can be used to control how a page is indexed by [
 
 You may also set `search` to a boolean value, which acts as an `exclude` value. See the first example below.
 
+#### Preview
+
+The `preview` frontmatter field can be used to render a component preview at the start of the page. It has the following subfields:
+
+| Name     | Type     | Default | Description                                                                                                                                               |
+| -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`    | `string` | N/A     | The URL path to the live preview (e.g., `/sign-in`)                                                                                                       |
+| `shadcn` | `object` | N/A     | Optional object containing framework-specific shadcn component names for installation references that renders a button to copy the shadcn install command |
+
+The `shadcn` subfield supports the following framework keys:
+
+| Name     | Type     | Description                                                            |
+| -------- | -------- | ---------------------------------------------------------------------- |
+| `nextjs` | `string` | The name of the Next.js Shadcn component (e.g., `nextjs-sign-in-page`) |
+
 ##### Examples
 
+<details>
+<summary>Add a preview with live demo</summary>
+
+```diff
+  ---
+  title: Example
++ preview:
++   src: '/sign-in'
+  ---
+```
+
+</details>
+
+<details>
+<summary>Add a preview with Shadcn component reference</summary>
+
+```diff
+  ---
+  title: Example
++ preview:
++   src: '/sign-in'
++   shadcn:
++     nextjs: 'nextjs-sign-in-page'
+  ---
+```
+
+</details>
+
 <details>
 <summary>Exclude a page from search</summary>
 

@@ -2,10 +2,12 @@
 title: '`<SignIn />` component'
 description: Clerk's <SignIn /> component renders a UI for signing in users.
 sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend
+preview:
+  src: '/sign-in'
+  shadcn:
+    nextjs: 'nextjs-sign-in-page'
 ---
 
-![The \<SignIn /> component renders a UI for signing in users.](/docs/images/ui-components/sign-in.png){{ style: { maxWidth: '460px' } }}
-
 The `<SignIn />` component renders a UI to allow users to sign in or sign up by default. The functionality of the `<SignIn />` component is controlled by the instance settings you specify in the [Clerk Dashboard](https://dashboard.clerk.com), such as [sign-in and sign-up options](/docs/guides/configure/auth-strategies/sign-up-sign-in-options) and [social connections](/docs/guides/configure/auth-strategies/social-connections/all-providers). You can further customize your `<SignIn />` component by passing additional [properties](#properties) at the time of rendering.
 
 > [!NOTE]

@@ -2,10 +2,12 @@
 title: '`<SignUp />` component'
 description: Clerk's <SignUp /> component renders a UI for signing up users.
 sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend
+preview:
+  src: '/sign-up'
+  shadcn:
+    nextjs: 'nextjs-sign-up-page'
 ---
 
-![The \<SignUp /> component renders a UI for signing up users.](/docs/images/ui-components/sign-up.png){{ style: { maxWidth: '460px' } }}
-
 The `<SignUp />` component renders a UI for signing up users. The functionality of the `<SignUp />` component is controlled by the instance settings you specify in the [Clerk Dashboard](https://dashboard.clerk.com), such as [sign-in and sign-up options](/docs/guides/configure/auth-strategies/sign-up-sign-in-options) and [social connections](/docs/guides/configure/auth-strategies/social-connections/all-providers). You can further customize your `<SignUp />` component by passing additional [properties](#properties) at the time of rendering.
 
 > [!NOTE]

@@ -2,10 +2,10 @@
 title: '`<TaskChooseOrganization />` component'
 description: Clerk's <TaskSelectComponent /> component renders a UI for resolving the `choose-organization` task.
 sdk: js-frontend, nextjs, react, react-router, remix, tanstack-react-start
+preview:
+  src: '/task-choose-organization'
 ---
 
-![The \<TaskChooseOrganization /> component renders a UI for resolving the choose-organization session task.](/docs/images/ui-components/task-choose-organization.png){{ style: { maxWidth: '460px' } }}
-
 The `<TaskChooseOrganization />` component renders a UI for resolving the `choose-organization` session task. The functionality of the `<TaskChooseOrganization />` component is controlled by the instance settings you specify in the [Clerk Dashboard](https://dashboard.clerk.com), such as [sign-in and sign-up options](/docs/guides/configure/auth-strategies/sign-up-sign-in-options) and [social connections](/docs/guides/configure/auth-strategies/social-connections/overview). You can further customize your `<TaskChooseOrganization />` component by passing additional [properties](#properties) at the time of rendering.
 
 > [!IMPORTANT]

@@ -2,10 +2,10 @@
 title: '`<Waitlist />` component'
 description: The <Waitlist /> component renders a waitlist form that allows users to join for early access to your application.
 sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend
+preview:
+  src: '/waitlist'
 ---
 
-![The \<Waitlist /> component renders a form that allows users to join for early access to your app.](/docs/images/ui-components/waitlist.png){{ style: { maxWidth: '460px' } }}
-
 In **Waitlist** mode, users can register their interest in your app by joining a waitlist. This mode is ideal for apps in early development stages or those wanting to generate interest before launch. [Learn more about additional features available in **Waitlist** mode](/docs/guides/secure/restricting-access#waitlist).
 
 The `<Waitlist />` component renders a form that allows users to join for early access to your app.

@@ -2,10 +2,10 @@
 title: '`<PricingTable />`'
 description: Clerk's <PricingTable /> component displays a table of Plans and Features that users can subscribe to.
 sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend
+preview:
+  src: '/pricing-table'
 ---
 
-![The \<PricingTable /> component displays a table of Plans and Features that users can subscribe to.](/docs/images/ui-components/pricing-table.png)
-
 The `<PricingTable />` component displays a table of Plans and Features that users can subscribe to.
 
 <If

@@ -2,10 +2,10 @@
 title: '`<CreateOrganization />` component'
 description: Clerk's <CreateOrganization /> component is used to render an organization creation UI that allows users to create brand new organizations within your application.
 sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend
+preview:
+  src: '/create-organization'
 ---
 
-![The \<CreateOrganization /> component renders an organization creation UI that allows users to create brand new organizations within your application.](/docs/images/ui-components/create-organization.png){{ style: { maxWidth: '492px' } }}
-
 The `<CreateOrganization />` component is used to render an organization creation UI that allows users to create brand new organizations in your application.
 
 <If

@@ -2,10 +2,10 @@
 title: '`<OrganizationList />` component'
 description: Clerk's <OrganizationList /> component is used to display organization related memberships, invitations, and suggestions for the user.
 sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend
+preview:
+  src: '/organization-list'
 ---
 
-![The \<OrganizationList /> component displays organization-related memberships and automatic invitations and suggestions for the user.](/docs/images/ui-components/organization-list.png){{ style: { maxWidth: '460px' } }}
-
 The `<OrganizationList />` component displays organization-related memberships and automatic [invitations](/docs/guides/organizations/verified-domains#automatic-invitations) and [suggestions](/docs/guides/organizations/verified-domains#automatic-suggestions) for the user.
 
 <If

@@ -2,10 +2,10 @@
 title: '`<OrganizationProfile />` component'
 description: Clerk's <OrganizationProfile /> component is used to render a beautiful, full-featured organization management UI that allows users to manage their organization profile and security settings.
 sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend
+preview:
+  src: '/organization-profile'
 ---
 
-![The \<OrganizationProfile /> component allows users to manage their organization membership and security settings.](/docs/images/ui-components/organization-profile.png)
-
 The `<OrganizationProfile />` component allows users to manage their organization membership, security, and billing settings.
 
 This component's **General** tab displays the organization's information and the **Leave organization** button. Admins will be able to see the **Update profile** button, **Verified domains** section, and **Delete organization** button.

@@ -2,10 +2,10 @@
 title: '`<OrganizationSwitcher />` component'
 description: Clerk's <OrganizationSwitcher /> component is used to enable the ability to switch between available organizations the user may be part of in your application.
 sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend
+preview:
+  src: '/organization-switcher'
 ---
 
-![The \<OrganizationSwitcher /> component allows a user to switch between their account types - their personal account and their joined organizations.](/docs/images/ui-components/organization-switcher.png){{ style: { maxWidth: '436px' } }}
-
 The `<OrganizationSwitcher />` component allows a user to switch between their joined organizations. If [personal accounts are enabled](/docs/guides/organizations/overview#allow-personal-accounts), users can also switch to their personal account. This component is useful for applications that have a multi-tenant architecture, where users can be part of multiple organizations. It handles all organization-related flows, including full organization management for admins. Learn more about [organizations](/docs/guides/organizations/overview).
 
 <If

@@ -4,10 +4,10 @@ description: Clerk's <UserButton /> component is used to render the familiar use
 search:
   rank: 1
 sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend
+preview:
+  src: '/user-button'
 ---
 
-![The \<UserButton /> component renders the familiar user button UI popularized by Google.](/docs/images/ui-components/user-button.png){{ style: { maxWidth: '436px' } }}
-
 The `<UserButton />` component renders the familiar user button UI popularized by Google. When selected, it opens a dropdown menu with options to manage account settings and sign out. The "Manage account" option launches the [`<UserProfile />`](/docs/reference/components/user/user-profile) component, providing access to profile and security settings.
 
 For users that have [multi-session](/docs/guides/secure/session-options#multi-session-applications) enabled, the `<UserButton />` also allows users to sign into multiple accounts at once and instantly switch between them without the need for a full page reload. Learn more [here](/docs/guides/secure/session-options#multi-session-applications).

@@ -2,10 +2,10 @@
 title: '`<UserProfile />` component'
 description: Clerk's <UserProfile /> component is used to render a beautiful, full-featured account management UI that allows users to manage their profile and security settings.
 sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend
+preview:
+  src: '/user-profile'
 ---
 
-![The \<UserProfile /> component renders a full-featured account management UI that allows users to manage their profile and security settings.](/docs/images/ui-components/user-profile.png){{ style: { maxWidth: '100%' } }}
-
 The `<UserProfile />` component is used to render a beautiful, full-featured account management UI that allows users to manage their profile, security, and billing settings.
 
 <If