@clerk/ui

Minor Changes

• Support passkeys as a second factor during sign-in and session reverification.

  When a user has a passkey, the prebuilt <SignIn/> and <UserVerification/> components preselect it as the second factor, as they already do for the first factor. Other methods stay available under "Use another method".

  To use it, your instance must allow passkeys to satisfy the second factor. This is on by default for instances created after 2026-07-08, and can be turned on in the Dashboard for older ones. Web apps also need to opt in to the passkey second factor update in the Dashboard.

  If you build a custom flow, supportedSecondFactors can now include passkey. Call signIn.authenticateWithPasskey() to complete it.

  Passkeys are no longer preselected, for either factor, where the SDK reports that WebAuthn is unavailable (for example, Electron apps without passkey support enabled).

Patch Changes

• Fix the OrganizationProfile sidebar to hide API keys when the user has neither org:sys_api_keys:read nor org:sys_api_keys:manage permission.

Minor Changes

• Add a role mapping step to the self-serve Directory Sync setup in <OrganizationProfile />. Organization admins can now assign an organization role to each directory group their identity provider pushes, set which group wins when a member belongs to several, and turn role syncing on or off. Members in no mapped group keep the organization's default role. The step is read-only for members without the org:sys_memberships:manage permission and while the organization's role set is being migrated.

Patch Changes

• Add an enterpriseConnectionsUrl option to handleRedirectCallback() and <AuthenticateWithRedirectCallback />. When the Clerk API asks an OAuth sign-up to choose between several enterprise connections for the same email domain, the callback navigates to this URL, which defaults to the enterprise-connections route of your sign-up page.

Minor Changes

• The self-serve SSO configuration (<OrganizationProfile /> enterprise connection page and the ConfigureSSO SAML steps) now shows every IdP signing certificate a SAML connection trusts, with its expiry, and lets an admin add certificates from a file (a PEM bundle adds several) or remove one, so an IdP key rotation no longer needs a replacement timed with the IdP. Saving sends the whole list and only when it changed. The list holds at most five certificates. New configureSSOCertificateList* and configureSSOCertificatePrimaryBadge appearance element descriptors cover the list, and new configureSSO.signingCertificates.* localization keys hold its strings.

Patch Changes

• Fixed <SignIn /> in the combined sign-in-or-up flow sending users back to the start after an OAuth or SAML redirect when the sign-in still needed a step, such as a Clerk Protect check, a second factor, or a password reset. Sign-ups created from an OAuth sign-in, including after a Protect check, now continue to their remaining steps inside the component.

• Fix the "Set as default" action for SMS second factors in <UserProfile />. It now prompts for reverification when required instead of showing a raw error, and it's no longer offered while an authenticator app is enrolled, since the authenticator app is always the default in that case.

Minor Changes

• Custom flows built with useSignIn() and useSignUp() now handle Clerk Protect challenges for you. When a sign-in or sign-up method gets a challenge, Clerk shows it in a modal and the method returns once the user passes it. For SSO, the challenge appears when the user comes back to <HandleSSOCallback />. Classic resource methods such as clerk.client.signIn.create(), and apps without Clerk's UI loaded, still return with protectCheck set, as before.

Patch Changes

• The Solana wallet picker downloads about 2 KB instead of about 306 KB, and installing @clerk/ui or @clerk/clerk-js no longer pulls in React Native, Metro, and @solana/web3.js. The picker now lists only wallets that can complete Sign in with Solana, so the Mobile Wallet Adapter option that appeared on Android Chrome is gone.

Minor Changes

• Support Google Workspace directories in Directory Sync. Organization admins can upload a service account key and delegated admin email from the setup flow, start a sync on demand, and see the result of the last one. DirectorySync gains setCredentials(), sync(), getSyncStatus(), and credentialsConfigured.

• Update the SSO and Directory Sync sections of the <OrganizationProfile /> Security page to the latest designs. Both sections now show a "Configure" button until something is set up (SSO then shows "Add connection"), and SSO connection rows show the identity provider's logo and an actions menu (Edit, Continue configuration, Activate/Deactivate, Remove). These actions have been removed from the SSO connection page, and status badges are no longer color-coded. Okta logos now follow the theme's foreground color, so they stay visible in dark mode, including on the enterprise connection chooser and in <UserProfile />.

  The SSO button uses the new ssoSection.primaryButton__configure localization key; ssoSection.primaryButton__startConfiguration is deprecated and no longer used. In directorySyncSection, primaryButton__startConfiguration is renamed to primaryButton__configure and badge__unconfigured is removed.

Patch Changes

• Use a React 19-safe boolean inert value when the sign-in or sign-up captcha becomes interactive, so the form is actually inert and the empty-string warning is gone.

• Fix abandoned passkey registrations counting toward the limit on unverified identifications. Cancelling or failing the browser passkey prompt left a pending registration on the account that is hidden from the user's passkey list, so it could silently block adding an email address or phone number until it expired. The pending registration is now removed as soon as the prompt is abandoned. In <UserProfile />, the "Add a passkey" button also shows a loading state while a registration is in progress, and a failed attempt no longer leaves its error banner on screen after a later attempt succeeds.

Minor Changes

• <SignIn /> and <SignUp /> show a dedicated screen when a request is blocked, with a reference the user can quote to support.

  action_blocked errors now expose traceId, title, description, linkUrl, linkText, kind and data on meta.

Patch Changes

• Clear the invitation ticket from the URL when a sign-in completes on a verification challenge.

• Fix enterprise SSO sign-ins erroring instead of showing a verification challenge raised while handing off to the identity provider.

  If you use the prebuilt <SignIn /> component, there is nothing to do. If you have Clerk Protect enabled and call signIn.authenticateWithRedirect() or signIn.authenticateWithPopup() from a custom sign-in flow, catch a ClerkRuntimeError with code protect_check_required and show the verification challenge, to avoid a stalled sign-in.

  That error means a verification challenge has to be completed before the sign-in can redirect. It replaces the generic "not supported" error these methods threw before. When it is thrown, the sign-in is gated: signIn.protectCheck is set, or its status is needs_protect_check. For enterprise SSO, run the challenge and then call authenticateWithRedirect() again with continueSignIn: true. If the server has already prepared the redirect, the sign-in continues to the identity provider and the challenge runs when it returns, so no error is thrown.

• Fix the verification challenge card spinning indefinitely when continuing the sign-in after a completed challenge fails. The error is now shown, and "Try again" retries the continuation.

• Fix sign-ins that use an enterprise connection stranding on "Use another method" after a verification challenge, instead of continuing to the identity provider.

Minor Changes

• The "Add members" card on the SSO allow list page of <OrganizationProfile /> now offers two ways to add people: by email address, or every member with a given role at once. Members whose email address is not served by one of the organization's enterprise connections are skipped. When nothing could be added the card stays open and says why, and when some were added it moves to a success step that reports how many were skipped.

  For custom flows, organization.ssoBypassAllowlist gains addUsers({ userIds }), which calls the new bulk endpoint in batches of 100 and returns the added entries together with the users that could not be added and why.

  Inputs marked to be ignored by password managers now also carry the Bitwarden, LastPass and Dashlane opt-out attributes, so those extensions stop offering to fill fields such as the allow list email address.

  The member picker that the "Add member" card shipped with in 4.18.0 is gone, and so are its localization keys under organizationProfile.securityPage.ssoBypassPage.addForm: memberLabel, memberPlaceholder, changeButton and noResults. The feature was never enabled on any instance, so no application depends on them.

  New customization handles: the organizationProfileSecuritySsoBypassEmailInput, organizationProfileSecuritySsoBypassRoleWarning, organizationProfileSecuritySsoBypassFailure and organizationProfileSecuritySsoBypassBulkResult appearance elements.

Patch Changes

• Show the provider logo next to each connection name on the enterprise account chooser.

• Localize icon-only social sign-in button names using socialButtonsBlockButton and exclude decorative provider icons from the accessibility tree. Add formFieldAction__showPassword and formFieldAction__hidePassword localization keys for password visibility controls, with translations for every supported locale and English fallback for older localization resources.

• Fix <UserProfile /> crashing with "Rendered fewer hooks than expected" after connecting the last available Web3 wallet.

Minor Changes

• Rename the SSO fallback sign-in flow to SSO bypass, matching the name the feature ships under. The sign-in resource's ssoFallbackFirstFactors is now ssoBypassFirstFactors and reads the sso_bypass_first_factors field from the API, the signIn.ssoFallback localization keys are now signIn.ssoBypass, and the ssoFallback card action element id is now ssoBypass. The flow has not been enabled on any instance, so no application is affected by the old names going away.

• Add the ability for Organization admins to manage the SSO bypass allowlist from the Security page of <OrganizationProfile />.

  For custom flows, organization.ssoBypassAllowlist exposes getUsers(), addUser({ userId }) and removeUser(userId).

Patch Changes

• Add @clerk/shared/phone with Clerk's country metadata and phone-number parsing, formatting, and detection helpers.

• Fix reconnecting disconnected Google One Tap accounts in UserProfile to use Google OAuth while preserving session reverification.

• Each enterprise connection listed on the organization Security page now opens its own page. It lists the connection name and domains, the service provider values to copy into the identity provider, the identity provider configuration behind an Edit form, and the connection settings as a form you save. The header carries one action, either Activate or Continue setup, and deactivating or removing the connection lives in a Danger zone section at the bottom of the page. The row menu is gone; click the row instead.

  The setup wizard's domains step now shows a checkbox per verified domain, so an admin picks which domains a connection covers. A domain another connection of the organization already authenticates is disabled and labelled with that connection's name, and an error from creating the connection is shown on the provider step instead of being dropped.

  New customization handles ship with it: the organizationProfileSecuritySsoConnectionRow and organizationProfileSecuritySsoConnectionPage appearance elements, the configureSSOVerifyDomainCardCheckbox element, the claimed badge id, the new FieldId values for the connection settings, and the ssoConnectionName, ssoConnectionDomains, ssoConnectionServiceProvider, ssoConnectionIdentityProvider, ssoConnectionSettings and ssoConnectionDangerZone ProfileSectionId values.

• Add @clerk/mosaic, an experimental standalone package for next generation Clerk components.

  If you try this out, make sure to pin your version as breaking changes can happen in minors.

• <OAuthConsent /> and <OAuthDeviceVerification /> no longer show an empty permissions list when an OAuth client requests only the offline_access scope.

• Add createDynamicParamParser and populateParamFromObject to @clerk/shared/url for resolving :property placeholders in URL templates.

Patch Changes

• Add agentid to OAuthProvider and OAUTH_PROVIDERS to support the "Continue with AgentID" OAuth flow. Instances with the connection enabled now render a "Continue with AgentID" button, with the AgentID mark tinted to match the theme's foreground color so it stays legible in dark mode.

• The organization Security page now lists every enterprise SSO connection of the organization, each with its own status, domains, and actions. The SSO wizard edits one explicit connection, and a banner names it when the organization has more than one. Changing a provider or removing a connection now targets that connection instead of the first one returned by the API.

• Validate appearance.cssLayerName before wrapping component styles in @layer. Values that are not a valid CSS layer name (for example ones containing braces, semicolons, or markup) are now ignored with a one-time console warning instead of being interpolated into the generated stylesheet.

Minor Changes

• Introduce self-serve Directory Sync (SCIM) capabilities and related functionality.

• Add the SSO fallback sign-in flow to <SignIn />, for enterprise users the instance has allowlisted to sign in with an email code when they cannot reach their identity provider.

  For such a user the sign-in no longer redirects straight to the identity provider. It shows the SSO action — or the connection picker, when several connections serve the address — alongside a "Can't use SSO?" link leading to the standard email code step, which carries a notice that the organization requires single sign-on and that the attempt is recorded. Users without a fallback, and instances without the feature, are unaffected.

  Custom flows can read the same factor from the new ssoFallbackFirstFactors property on the sign-in resource. The flow adds the signIn.enterpriseSSO and signIn.ssoFallback localization keys and the ssoFallback card action element id.

Patch Changes

• Fixed OAuth sign-ups from openSignIn({ withSignUp: true }) landing on the sign-in page with an "External Account was not found" error instead of creating the account.

Patch Changes

• Update Clerk Dashboard links in option descriptions, error messages, and READMEs to use the active-instance shortcut (https://dashboard.clerk.com/~/…) instead of the legacy /last-active?path=… URL.

• Hide "Use another method" during reverification when the current factor is the only available method.

• Prevent passkey autofill from displaying an RP ID or domain error when a browser rejects a background credential request.

• Update the @floating-ui/react dependency to 0.27.20.

Minor Changes

• Add an authenticated OAuth device verification component and workflow hook for approving or denying OAuth Device Authorization Grant requests.

Patch Changes

• Fix configured OIDC prompts being ignored by sign-up continuations, including enterprise SSO after email-link verification or direct combined-flow transfer and OAuth sign-ups embedded in <SignIn withSignUp>.

Minor Changes

• Add the Mosaic Banner component: a tinted surface that annotates the content around it with a status message. Compose it from Banner.Root, Banner.Label, and Banner.Description. Banner.Root takes a color of neutral, warning, or negative, and renders the icon for that color itself. It sets no ARIA role, so pass role='status' (or role='alert') when the banner appears in response to something the user did.

  Also adds an info-circle glyph to the Mosaic icon set.

Patch Changes

• Fix an issue where a verification that was still progressing normally could be cancelled and reported to the user as having timed out.

Patch Changes

• Keep Clerk's navigation inside the renderer. ClerkProvider now always supplies routerPush/routerReplace, so Clerk routes through your application's router when you provide one, and never navigates the window to an internal /CLERK-ROUTER/VIRTUAL/... path — which no custom protocol handler can serve, and which reloaded the renderer and dropped the user out of sign-in.

  Applications that worked around this by passing no-op router functions, or by filtering CLERK-ROUTER/VIRTUAL out themselves, can remove those workarounds.

• Fixes an issue where OAuth account transfers that needed additional verification were returned to the beginning of sign-in.

• Route an OAuth transfer to the sign-up continue step when sign-in uses a native OAuth transport. The callback previously navigated with hash-style URLs (<sign-up-url>#/continue) that the in-place component router cannot resolve, landing transferred sign-ups on the start card where submitting created a fresh sign-up without the verified external account.

• Fix an issue where sign-ups that used an enterprise SSO connection did not correctly forward redirect URLs.

Patch Changes

• Display a proper message when a password is rejected for matching one of the account's identifiers. Previously this error rendered as the incomplete sentence "Your password must contain ." on sign-up, reset password, and the user profile password form. The new message is available under the unstable__errors.form_password_matches_identifier localization key, and any password error the UI does not recognize now falls back to the message returned by the API instead of an empty sentence.

Patch Changes

• Add a "Back" action to the sign-in second-factor and client-trust steps, letting a stuck user abandon the attempt and return to the sign-in start.

Patch Changes

• Billing applied-discount snapshots now include optional durationInCycles. Payment attempt and statement UIs use the original discount length instead of cycles remaining, and omit the duration copy when it is unavailable.

Patch Changes

• Fix native OAuth transport flows (e.g. @clerk/electron) breaking out of modal components and failing with "Redirect url mismatch" errors.

  Intermediate OAuth callback steps (sign-in to sign-up transfer, continue, MFA factors, password reset) now navigate inside the component's own router instead of navigating the app window to an internal Clerk route. Transport flows also always send the registered transport callback URL as the completion redirect, so production instances no longer reject sign-in or sign-up requests when a page-derived URL was picked up as the completion redirect.

Patch Changes

• Hide the “Use another method” action during Device Trust and second-factor verification when no alternative verification method is available.

Minor Changes

• Add <InviteMembersButton />, a control component that opens the organization invite-members form in a modal when clicked, working like <SignInButton mode="modal">.

  Wrap your own button (or omit children for a default one). The button requires an active organization and should be rendered for members who can manage memberships (org:sys_memberships:manage). Opening it without an active organization or that permission is a no-op in production, and throws a descriptive error in development.

  import { InviteMembersButton } from '@clerk/nextjs';
  
  <InviteMembersButton>
    <button>Invite members</button>
  </InviteMembersButton>;

  This also adds Clerk.openInviteMembers() and Clerk.closeInviteMembers() for opening and closing the modal programmatically.

Patch Changes

• Ensure drawers opened from modals render above the modal and its backdrop.

• Keep invitation email pills consistently spaced when they wrap across multiple rows.

Minor Changes

• Support sign-in-or-sign-up combined flow with Clerk <SignIn> component

  when strict enumeration protection is enabled.

  On development instances, <SignIn> now logs a warning when the sign-in-or-up flow is rendered on an instance that has both password and strict enumeration protection enabled. In that configuration visitors without an account are routed to the password screen and cannot complete a sign-up, so the warning names both settings and how to resolve them.

Patch Changes

• ui: Avoid races between email link tabs when using sign up if missing

Patch Changes

• Enable self-serve OIDC configuration for every application. Organization admins can now select an OIDC provider in the <OrganizationProfile /> Security tab without the experimental.oidcSelfServe option, and existing OIDC connections open their configuration steps instead of the unsupported-provider state. The experimental.oidcSelfServe option no longer does anything and can be removed from <ClerkProvider /> and Clerk.load().

Minor Changes

• Add a new Mosaic Avatar compound component (StyleX). Avatar.Root owns shape (circle | square) and size (lg | md | sm | xs); compose Avatar.Image (renders once the image loads) and Avatar.Fallback (shown while the image is pending or has failed, with an optional delayMs) inside it.

Patch Changes

• Add support for configuring custom OpenID Connect enterprise connections through the Organization Profile.

• Expose whether an organization member has been deprovisioned, and mark deprovisioned members as inactive in the Organization Profile.