diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4cc9c60c26..5949ab0368 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 +
+Add a preview with live demo + +```diff + --- + title: Example ++ preview: ++ src: '/sign-in' + --- +``` + +
+ +
+Add a preview with Shadcn component reference + +```diff + --- + title: Example ++ preview: ++ src: '/sign-in' ++ shadcn: ++ nextjs: 'nextjs-sign-in-page' + --- +``` + +
+
Exclude a page from search diff --git a/docs/reference/components/authentication/sign-in.mdx b/docs/reference/components/authentication/sign-in.mdx index 8b0ff39d53..ab96448cd2 100644 --- a/docs/reference/components/authentication/sign-in.mdx +++ b/docs/reference/components/authentication/sign-in.mdx @@ -2,10 +2,12 @@ title: '`` component' description: Clerk's 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 \ component renders a UI for signing in users.](/docs/images/ui-components/sign-in.png){{ style: { maxWidth: '460px' } }} - The `` component renders a UI to allow users to sign in or sign up by default. The functionality of the `` 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 `` component by passing additional [properties](#properties) at the time of rendering. > [!NOTE] diff --git a/docs/reference/components/authentication/sign-up.mdx b/docs/reference/components/authentication/sign-up.mdx index e641cb48e8..b50b10b9de 100644 --- a/docs/reference/components/authentication/sign-up.mdx +++ b/docs/reference/components/authentication/sign-up.mdx @@ -2,10 +2,12 @@ title: '`` component' description: Clerk's 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 \ component renders a UI for signing up users.](/docs/images/ui-components/sign-up.png){{ style: { maxWidth: '460px' } }} - The `` component renders a UI for signing up users. The functionality of the `` 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 `` component by passing additional [properties](#properties) at the time of rendering. > [!NOTE] diff --git a/docs/reference/components/authentication/task-choose-organization.mdx b/docs/reference/components/authentication/task-choose-organization.mdx index e54f5fa546..e40c7a989a 100644 --- a/docs/reference/components/authentication/task-choose-organization.mdx +++ b/docs/reference/components/authentication/task-choose-organization.mdx @@ -2,10 +2,10 @@ title: '`` component' description: Clerk's 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 \ component renders a UI for resolving the choose-organization session task.](/docs/images/ui-components/task-choose-organization.png){{ style: { maxWidth: '460px' } }} - The `` component renders a UI for resolving the `choose-organization` session task. The functionality of the `` 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 `` component by passing additional [properties](#properties) at the time of rendering. > [!IMPORTANT] diff --git a/docs/reference/components/authentication/waitlist.mdx b/docs/reference/components/authentication/waitlist.mdx index 9868e2172a..da8a2c511c 100644 --- a/docs/reference/components/authentication/waitlist.mdx +++ b/docs/reference/components/authentication/waitlist.mdx @@ -2,10 +2,10 @@ title: '`` component' description: The 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 \ 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 `` component renders a form that allows users to join for early access to your app. diff --git a/docs/reference/components/billing/pricing-table.mdx b/docs/reference/components/billing/pricing-table.mdx index 4f6a01cacc..d8702f1561 100644 --- a/docs/reference/components/billing/pricing-table.mdx +++ b/docs/reference/components/billing/pricing-table.mdx @@ -2,10 +2,10 @@ title: '``' description: Clerk's 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 \ component displays a table of Plans and Features that users can subscribe to.](/docs/images/ui-components/pricing-table.png) - The `` component displays a table of Plans and Features that users can subscribe to. ` component' description: Clerk's 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 \ 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 `` component is used to render an organization creation UI that allows users to create brand new organizations in your application. ` component' description: Clerk's 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 \ component displays organization-related memberships and automatic invitations and suggestions for the user.](/docs/images/ui-components/organization-list.png){{ style: { maxWidth: '460px' } }} - The `` 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. ` component' description: Clerk's 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 \ component allows users to manage their organization membership and security settings.](/docs/images/ui-components/organization-profile.png) - The `` 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. diff --git a/docs/reference/components/organization/organization-switcher.mdx b/docs/reference/components/organization/organization-switcher.mdx index b63cd362dd..e4ea817b3c 100644 --- a/docs/reference/components/organization/organization-switcher.mdx +++ b/docs/reference/components/organization/organization-switcher.mdx @@ -2,10 +2,10 @@ title: '`` component' description: Clerk's 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 \ 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 `` 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). 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 \ component renders the familiar user button UI popularized by Google.](/docs/images/ui-components/user-button.png){{ style: { maxWidth: '436px' } }} - The `` 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 [``](/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 `` 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). diff --git a/docs/reference/components/user/user-profile.mdx b/docs/reference/components/user/user-profile.mdx index 8a878f1df5..4a855d65f7 100644 --- a/docs/reference/components/user/user-profile.mdx +++ b/docs/reference/components/user/user-profile.mdx @@ -2,10 +2,10 @@ title: '`` component' description: Clerk's 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 \ 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 `` component is used to render a beautiful, full-featured account management UI that allows users to manage their profile, security, and billing settings.