From f3935adf91cfab92852248eeec8b3aa360b6a0ea Mon Sep 17 00:00:00 2001 From: Alex Carpenter Date: Fri, 24 Oct 2025 10:53:38 -0400 Subject: [PATCH 1/6] feat: Add custom flows guide on using lastAuthenticationStrategy --- .../last-authentication-strategy.mdx | 147 ++++++++++++++++++ docs/manifest.json | 4 + 2 files changed, 151 insertions(+) create mode 100644 docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx diff --git a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx new file mode 100644 index 0000000000..05a1e4f015 --- /dev/null +++ b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx @@ -0,0 +1,147 @@ +--- +title: Add a badge to show the last authentication method +description: Learn how to use the lastAuthenticationStrategy property to highlight the last used OAuth provider with a badge. +--- + + + +The `Client` object includes a `lastAuthenticationStrategy` property that tracks the last authentication method used by the user. This is useful for improving UX by showing a "Last used" badge on OAuth buttons, helping returning users quickly identify their preferred sign-in method. + + + ## Access the last authentication strategy + + The `lastAuthenticationStrategy` property is available on the [`Client`](/docs/reference/javascript/client) object. You can access it through the `client` property of the [`Clerk`](/docs/reference/javascript/clerk) instance. + + + + This example is written for Next.js App Router but it can be adapted for any React-based framework. + + The following example demonstrates how to: + + 1. Access the `client` object using the [`useClerk()`](/docs/reference/hooks/use-clerk) hook. + 1. Check the `lastAuthenticationStrategy` property to identify which OAuth provider was last used. + 1. Display a badge next to the corresponding OAuth button. + + ```tsx {{ filename: 'app/sign-in/page.tsx' }} + 'use client' + + import * as React from 'react' + import { OAuthStrategy } from '@clerk/types' + import { useSignIn, useClerk } from '@clerk/nextjs' + + export default function Page() { + const { signIn } = useSignIn() + const { client } = useClerk() + + if (!signIn) return null + + const lastStrategy = client?.lastAuthenticationStrategy + + const signInWith = (strategy: OAuthStrategy) => { + return signIn.authenticateWithRedirect({ + strategy, + redirectUrl: '/sign-in/sso-callback', + redirectUrlComplete: '/', + }) + } + + const providers = [ + { strategy: 'oauth_google' as const, name: 'Google' }, + { strategy: 'oauth_github' as const, name: 'GitHub' }, + ] + + return ( +
+

Sign in

+ {providers.map((provider) => ( + + ))} +
+ ) + } + ``` + + + + The following example demonstrates how to: + + 1. Access the `client` object from the `Clerk` instance. + 1. Check the `lastAuthenticationStrategy` property to identify which OAuth provider was last used. + 1. Display a badge next to the corresponding OAuth button. + + ```html {{ filename: 'index.html', collapsible: true }} + + + + + + Clerk + JavaScript App + + +
+ + + + + ``` + + ```js {{ filename: 'main.js', collapsible: true }} + import { Clerk } from '@clerk/clerk-js' + + const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + const clerk = new Clerk(pubKey) + await clerk.load() + + if (clerk.user) { + // User is already signed in + document.getElementById('app').innerHTML = ` +
+ ` + clerk.mountUserButton(document.getElementById('user-button')) + } else { + const lastStrategy = clerk.client?.lastAuthenticationStrategy + + const providers = [ + { strategy: 'oauth_google', name: 'Google' }, + { strategy: 'oauth_github', name: 'GitHub' }, + ] + + const buttons = providers + .map( + (provider) => ` + + `, + ) + .join('') + + document.getElementById('app').innerHTML = ` +

Sign in

+ ${buttons} + ` + + providers.forEach((provider) => { + document.getElementById(provider.strategy)?.addEventListener('click', async () => { + try { + await clerk.client.signIn.authenticateWithRedirect({ + strategy: provider.strategy, + redirectUrl: '/sso-callback', + redirectUrlComplete: '/', + }) + } catch (error) { + console.error('Error:', error) + } + }) + }) + } + ``` + + + + diff --git a/docs/manifest.json b/docs/manifest.json index fff9c8650a..fad2461d77 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -975,6 +975,10 @@ "title": "OAuth connections", "href": "/docs/guides/development/custom-flows/authentication/oauth-connections" }, + { + "title": "Add a badge to show the last authentication strategy", + "href": "/docs/guides/development/custom-flows/authentication/last-authentication-strategy" + }, { "title": "Enterprise connections", "href": "/docs/guides/development/custom-flows/authentication/enterprise-connections" From f86a7039bbfa9b54ad13d16245d89f2f66fbeba9 Mon Sep 17 00:00:00 2001 From: Alex Carpenter Date: Fri, 24 Oct 2025 10:55:30 -0400 Subject: [PATCH 2/6] format --- .../custom-flows/authentication/last-authentication-strategy.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx index 05a1e4f015..bace2873af 100644 --- a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx +++ b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx @@ -144,4 +144,3 @@ The `Client` object includes a `lastAuthenticationStrategy` property that tracks - From 5d15177945dc3363130e227e3983a223c3e98dff Mon Sep 17 00:00:00 2001 From: Alex Carpenter Date: Fri, 24 Oct 2025 10:59:32 -0400 Subject: [PATCH 3/6] remove steps --- .../last-authentication-strategy.mdx | 266 +++++++++--------- 1 file changed, 132 insertions(+), 134 deletions(-) diff --git a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx index bace2873af..5aa3a9c6e5 100644 --- a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx +++ b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx @@ -7,140 +7,138 @@ description: Learn how to use the lastAuthenticationStrategy property to highlig The `Client` object includes a `lastAuthenticationStrategy` property that tracks the last authentication method used by the user. This is useful for improving UX by showing a "Last used" badge on OAuth buttons, helping returning users quickly identify their preferred sign-in method. - - ## Access the last authentication strategy - - The `lastAuthenticationStrategy` property is available on the [`Client`](/docs/reference/javascript/client) object. You can access it through the `client` property of the [`Clerk`](/docs/reference/javascript/clerk) instance. - - - - This example is written for Next.js App Router but it can be adapted for any React-based framework. - - The following example demonstrates how to: - - 1. Access the `client` object using the [`useClerk()`](/docs/reference/hooks/use-clerk) hook. - 1. Check the `lastAuthenticationStrategy` property to identify which OAuth provider was last used. - 1. Display a badge next to the corresponding OAuth button. - - ```tsx {{ filename: 'app/sign-in/page.tsx' }} - 'use client' - - import * as React from 'react' - import { OAuthStrategy } from '@clerk/types' - import { useSignIn, useClerk } from '@clerk/nextjs' - - export default function Page() { - const { signIn } = useSignIn() - const { client } = useClerk() - - if (!signIn) return null - - const lastStrategy = client?.lastAuthenticationStrategy - - const signInWith = (strategy: OAuthStrategy) => { - return signIn.authenticateWithRedirect({ - strategy, - redirectUrl: '/sign-in/sso-callback', - redirectUrlComplete: '/', - }) - } - - const providers = [ - { strategy: 'oauth_google' as const, name: 'Google' }, - { strategy: 'oauth_github' as const, name: 'GitHub' }, - ] - - return ( -
-

Sign in

- {providers.map((provider) => ( - - ))} -
- ) +## Access the last authentication strategy + +The `lastAuthenticationStrategy` property is available on the [`Client`](/docs/reference/javascript/client) object. You can access it through the `client` property of the [`Clerk`](/docs/reference/javascript/clerk) instance. + + + + This example is written for Next.js App Router but it can be adapted for any React-based framework. + + The following example demonstrates how to: + + 1. Access the `client` object using the [`useClerk()`](/docs/reference/hooks/use-clerk) hook. + 1. Check the `lastAuthenticationStrategy` property to identify which OAuth provider was last used. + 1. Display a badge next to the corresponding OAuth button. + + ```tsx {{ filename: 'app/sign-in/page.tsx' }} + 'use client' + + import * as React from 'react' + import { OAuthStrategy } from '@clerk/types' + import { useSignIn, useClerk } from '@clerk/nextjs' + + export default function Page() { + const { signIn } = useSignIn() + const { client } = useClerk() + + if (!signIn) return null + + const lastStrategy = client?.lastAuthenticationStrategy + + const signInWith = (strategy: OAuthStrategy) => { + return signIn.authenticateWithRedirect({ + strategy, + redirectUrl: '/sign-in/sso-callback', + redirectUrlComplete: '/', + }) } - ``` - - - - The following example demonstrates how to: - - 1. Access the `client` object from the `Clerk` instance. - 1. Check the `lastAuthenticationStrategy` property to identify which OAuth provider was last used. - 1. Display a badge next to the corresponding OAuth button. - - ```html {{ filename: 'index.html', collapsible: true }} - - - - - - Clerk + JavaScript App - - -
- - - - - ``` - - ```js {{ filename: 'main.js', collapsible: true }} - import { Clerk } from '@clerk/clerk-js' - - const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY - - const clerk = new Clerk(pubKey) - await clerk.load() - - if (clerk.user) { - // User is already signed in - document.getElementById('app').innerHTML = ` -
- ` - clerk.mountUserButton(document.getElementById('user-button')) - } else { - const lastStrategy = clerk.client?.lastAuthenticationStrategy - - const providers = [ - { strategy: 'oauth_google', name: 'Google' }, - { strategy: 'oauth_github', name: 'GitHub' }, - ] - - const buttons = providers - .map( - (provider) => ` - - `, - ) - .join('') - - document.getElementById('app').innerHTML = ` + + const providers = [ + { strategy: 'oauth_google' as const, name: 'Google' }, + { strategy: 'oauth_github' as const, name: 'GitHub' }, + ] + + return ( +

Sign in

- ${buttons} - ` - - providers.forEach((provider) => { - document.getElementById(provider.strategy)?.addEventListener('click', async () => { - try { - await clerk.client.signIn.authenticateWithRedirect({ - strategy: provider.strategy, - redirectUrl: '/sso-callback', - redirectUrlComplete: '/', - }) - } catch (error) { - console.error('Error:', error) - } - }) + {providers.map((provider) => ( + + ))} +
+ ) + } + ``` + + + + The following example demonstrates how to: + + 1. Access the `client` object from the `Clerk` instance. + 1. Check the `lastAuthenticationStrategy` property to identify which OAuth provider was last used. + 1. Display a badge next to the corresponding OAuth button. + + ```html {{ filename: 'index.html', collapsible: true }} + + + + + + Clerk + JavaScript App + + +
+ + + + + ``` + + ```js {{ filename: 'main.js', collapsible: true }} + import { Clerk } from '@clerk/clerk-js' + + const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + const clerk = new Clerk(pubKey) + await clerk.load() + + if (clerk.user) { + // User is already signed in + document.getElementById('app').innerHTML = ` +
+ ` + clerk.mountUserButton(document.getElementById('user-button')) + } else { + const lastStrategy = clerk.client?.lastAuthenticationStrategy + + const providers = [ + { strategy: 'oauth_google', name: 'Google' }, + { strategy: 'oauth_github', name: 'GitHub' }, + ] + + const buttons = providers + .map( + (provider) => ` + + `, + ) + .join('') + + document.getElementById('app').innerHTML = ` +

Sign in

+ ${buttons} + ` + + providers.forEach((provider) => { + document.getElementById(provider.strategy)?.addEventListener('click', async () => { + try { + await clerk.client.signIn.authenticateWithRedirect({ + strategy: provider.strategy, + redirectUrl: '/sso-callback', + redirectUrlComplete: '/', + }) + } catch (error) { + console.error('Error:', error) + } }) - } - ``` - - - + }) + } + ``` + + From 749e7b8f49c9c9e06805c5fd87691798718edb98 Mon Sep 17 00:00:00 2001 From: Alex Carpenter Date: Fri, 24 Oct 2025 15:25:07 -0400 Subject: [PATCH 4/6] Update docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx Co-authored-by: Sarah Soutoul --- .../authentication/last-authentication-strategy.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx index 5aa3a9c6e5..acc74dba2d 100644 --- a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx +++ b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx @@ -5,7 +5,7 @@ description: Learn how to use the lastAuthenticationStrategy property to highlig -The `Client` object includes a `lastAuthenticationStrategy` property that tracks the last authentication method used by the user. This is useful for improving UX by showing a "Last used" badge on OAuth buttons, helping returning users quickly identify their preferred sign-in method. +The `Client` object includes a `lastAuthenticationStrategy` property that tracks the last authentication method used by the user. This is useful for improving the user experience by showing a "Last used" badge on OAuth buttons, helping returning users quickly identify their preferred sign-in method. ## Access the last authentication strategy From 695cd8c4d8c7540a636fba8f52965de03dc98957 Mon Sep 17 00:00:00 2001 From: Alex Carpenter Date: Fri, 24 Oct 2025 15:25:13 -0400 Subject: [PATCH 5/6] Update docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx Co-authored-by: Sarah Soutoul --- .../authentication/last-authentication-strategy.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx index acc74dba2d..e1300fdc2d 100644 --- a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx +++ b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx @@ -1,5 +1,5 @@ --- -title: Add a badge to show the last authentication method +title: Build a custom flow for displaying the last authentication method description: Learn how to use the lastAuthenticationStrategy property to highlight the last used OAuth provider with a badge. --- From c13742520a67122c0d4e696cb591fd8acde33b2c Mon Sep 17 00:00:00 2001 From: Alex Carpenter Date: Fri, 24 Oct 2025 15:25:22 -0400 Subject: [PATCH 6/6] Update docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx Co-authored-by: Sarah Soutoul --- .../authentication/last-authentication-strategy.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx index e1300fdc2d..93cbb3f682 100644 --- a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx +++ b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx @@ -1,6 +1,6 @@ --- title: Build a custom flow for displaying the last authentication method -description: Learn how to use the lastAuthenticationStrategy property to highlight the last used OAuth provider with a badge. +description: Learn how to use the Clerk API to build a custom flow for displaying the `lastAuthenticationStrategy` property and highlighting the last used OAuth provider with a badge. ---