feat(core): Split setActive into selectSession and selectOrganization

.changeset/split-setactive-into-select-methods.md

@@ -0,0 +1,92 @@
+---
+'@clerk/clerk-js': major
+'@clerk/shared': major
+'@clerk/react': major
+'@clerk/nextjs': major
+'@clerk/vue': major
+'@clerk/expo': major
+'@clerk/ui': major
+'@clerk/testing': major
+---
+
+Replace `setActive` with purpose-specific methods: `selectSession` and `selectOrganization`
+
+## Breaking Changes
+
+### `setActive` Removed from Public API
+
+The `setActive` method has been removed from the Clerk object and all hooks. Use the new purpose-specific methods instead:
+
+- `clerk.selectSession(session, options?)` - For session selection
+- `clerk.selectOrganization(organization, options?)` - For organization selection
+
+### Hook Return Types
+
+The following hooks no longer return `setActive`:
+
+- `useSignIn()` - now returns `selectSession` instead of `setActive`
+- `useSignUp()` - now returns `selectSession` instead of `setActive`
+- `useSessionList()` - now returns `selectSession` instead of `setActive`
+- `useOrganizationList()` - now returns `selectOrganization` instead of `setActive`
+
+### Migration
+
+**Before:**
+```tsx
+const { setActive } = useSignIn();
+await setActive({ session: createdSessionId });
+
+const { setActive } = useOrganizationList();
+await setActive({ organization: org });
+```
+
+**After:**
+```tsx
+const { selectSession } = useSignIn();
+await selectSession(createdSessionId);
+
+const { selectOrganization } = useOrganizationList();
+await selectOrganization(org);
+```
+
+### New Methods on Clerk Object
+
+Two new methods are available on the Clerk object:
+
+- `clerk.selectSession(session, options?)` - For session selection (sign-in, sign-up, multi-session switching)
+- `clerk.selectOrganization(organization, options?)` - For organization selection (org switching, personal workspace)
+
+### Options
+
+Both methods accept an options object:
+
+```tsx
+// selectSession options
+await selectSession(session, {
+ redirectUrl?: string;
+ navigate?: ({ session }) => void | Promise<void>;
+});
+
+// selectOrganization options
+await selectOrganization(organization, {
+ redirectUrl?: string;
+ navigate?: ({ session, organization }) => void | Promise<void>;
+});
+```
+
+### Expo Hooks
+
+The `StartGoogleAuthenticationFlowReturnType` and `StartAppleAuthenticationFlowReturnType` types now return `selectSession` instead of `setActive`.
+
+### Internal Window Hooks (Next.js)
+
+The internal window hooks have been renamed:
+- `__internal_onBeforeSetActive` → `__internal_onBeforeSelectSession`
+- `__internal_onAfterSetActive` → `__internal_onAfterSelectSession`
+
+### Types Removed
+
+The following types have been removed from the public API:
+- `SetActive`
+- `SetActiveParams`
+- `SetActiveNavigate` (use `SelectSessionNavigate` instead)

packages/clerk-js/src/core/clerk.ts

@@ -97,6 +97,8 @@ import type {
  RedirectOptions,
  Resources,
  SDKMetadata,
+ SelectOrganizationOptions,
+ SelectSessionOptions,
  SessionResource,
  SetActiveParams,
  SignedInSessionResource,
@@ -297,7 +299,7 @@ export class Clerk implements ClerkInterface {
  public __internal_isWebAuthnAutofillSupported: (() => Promise<boolean>) | undefined;
  public __internal_isWebAuthnPlatformAuthenticatorSupported: (() => Promise<boolean>) | undefined;
 
- public __internal_setActiveInProgress = false;
+ public __internal_selectSessionInProgress = false;
 
  get publishableKey(): string {
  return this.#publishableKey;
@@ -583,13 +585,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  const opts = callbackOrOptions && typeof callbackOrOptions === 'object' ? callbackOrOptions : options || {};
@@ -1446,7 +1448,7 @@ export class Clerk implements ClerkInterface {
  public setActive = async (params: SetActiveParams): Promise<void> => {
  const { organization, redirectUrl, navigate: setActiveNavigate } = params;
  let { session } = params;
- this.__internal_setActiveInProgress = true;
+ this.__internal_selectSessionInProgress = true;
  debugLogger.debug(
  'setActive() start',
  {
@@ -1476,13 +1478,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  let newSession = session === undefined ? this.session : session;
@@ -1605,10 +1607,79 @@ export class Clerk implements ClerkInterface {
  await onAfterSetActive();
  }
  } finally {
- this.__internal_setActiveInProgress = false;
+ this.__internal_selectSessionInProgress = false;
  }
  };
 
+ /**
+ * Select a session to make active.
+ *
+ * Use this method after sign-in or sign-up to activate the created session,
+ * or to switch between sessions in a multi-session application.
+ *
+ * Pass `null` to sign out and clear the active session.
+ */
+ public selectSession = async (
+ session: SignedInSessionResource | string | null,
+ options?: SelectSessionOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session: s }: { session: SessionResource }) => {
+ const result = await navigate({ session: s });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ session,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
+ /**
+ * Select an organization to make active within the current session.
+ *
+ * Use this method to switch between organizations or to select a personal workspace.
+ *
+ * Pass `null` to switch to the personal workspace (no active organization).
+ */
+ public selectOrganization = async (
+ organization: OrganizationResource | string | null,
+ options?: SelectOrganizationOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session }: { session: SessionResource }) => {
+ // Resolve the organization for the callback
+ const org =
+ organization === null
+ ? null
+ : typeof organization === 'string'
+ ? (this.organization ?? null)
+ : organization;
+
+ const result = await navigate({ session, organization: org });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ organization,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
  public addListener = (listener: ListenerCallback): UnsubscribeCallback => {
  listener = memoizeListenerCallback(listener);
  this.#listeners.push(listener);
@@ -2596,8 +2667,8 @@ export class Clerk implements ClerkInterface {
  const hasTransitionedToPendingStatus = this.session.status === 'active' && session?.status === 'pending';
  if (hasTransitionedToPendingStatus) {
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  // Execute hooks to update server authentication context and trigger

packages/clerk-js/src/core/resources/BillingCheckout.ts

@@ -204,7 +204,7 @@ export class CheckoutFlow implements CheckoutFlowResourceNonStrict {
  throw new Error('Clerk: `confirm()` must be called before `finalize()`');
  }
 
- await BillingCheckout.clerk.setActive({ session: BillingCheckout.clerk.session?.id, navigate });
+ await BillingCheckout.clerk.selectSession(BillingCheckout.clerk.session?.id ?? null, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignIn.ts

@@ -1243,7 +1243,7 @@ class SignInFuture implements SignInFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignIn.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -972,7 +972,7 @@ class SignUpFuture implements SignUpFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignUp.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 }

packages/clerk-js/src/global.d.ts

@@ -15,8 +15,8 @@ const __BUILD_VARIANT_CHANNEL__: boolean;
 const __BUILD_VARIANT_CHIPS__: boolean;
 
 interface Window {
-__internal_onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
-__internal_onAfterSetActive: () => Promise<void> | void;
+__internal_onBeforeSelectSession: (intent?: 'sign-out') => Promise<void> | void;
+__internal_onAfterSelectSession: () => Promise<void> | void;
  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
  __internal_ClerkUiCtor?: import('@clerk/shared/types').ClerkUiConstructor;
  /**

packages/clerk-js/src/test/mock-helpers.ts

@@ -99,7 +99,8 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  });
 
  mockProp(clerkAny, 'navigate');
- mockProp(clerkAny, 'setActive');
+ mockProp(clerkAny, 'selectSession');
+ mockProp(clerkAny, 'selectOrganization');
  mockProp(clerkAny, 'redirectWithAuth');
  mockProp(clerkAny, '__internal_navigateWithError');
  return clerkAny as DeepVitestMocked<LoadedClerk>;

packages/expo/src/hooks/useOAuth.ts

@@ -1,5 +1,5 @@
 import { useSignIn, useSignUp } from '@clerk/react/legacy';
-import type { OAuthStrategy, SetActive, SignInResource, SignUpResource } from '@clerk/shared/types';
+import type { OAuthStrategy, SelectSessionHook, SignInResource, SignUpResource } from '@clerk/shared/types';
 import * as AuthSession from 'expo-auth-session';
 import * as WebBrowser from 'expo-web-browser';
 
@@ -18,7 +18,7 @@ export type StartOAuthFlowParams = {
 
 export type StartOAuthFlowReturnType = {
  createdSessionId: string;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
  authSessionResult?: WebBrowser.WebBrowserAuthSessionResult;
@@ -33,7 +33,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return errorThrower.throw('Missing oauth strategy');
  }
 
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startOAuthFlow(startOAuthFlowParams?: StartOAuthFlowParams): Promise<StartOAuthFlowReturnType> {
@@ -42,7 +42,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  createdSessionId: '',
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -79,7 +79,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId: '',
-setActive,
+selectSession,
  signIn,
  signUp,
  };
@@ -108,7 +108,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  };

packages/expo/src/hooks/useSSO.ts

@@ -2,7 +2,7 @@ import { useSignIn, useSignUp } from '@clerk/react/legacy';
 import type {
  EnterpriseSSOStrategy,
  OAuthStrategy,
-SetActive,
+SelectSessionHook,
  SignInResource,
  SignUpResource,
 } from '@clerk/shared/types';
@@ -28,13 +28,13 @@ export type StartSSOFlowParams = {
 export type StartSSOFlowReturnType = {
  createdSessionId: string | null;
  authSessionResult: WebBrowser.WebBrowserAuthSessionResult | null;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
 };
 
 export function useSSO() {
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startSSOFlow(startSSOFlowParams: StartSSOFlowParams): Promise<StartSSOFlowReturnType> {
@@ -44,7 +44,7 @@ export function useSSO() {
  authSessionResult: null,
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -81,7 +81,7 @@ export function useSSO() {
  if (authSessionResult.type !== 'success' || !authSessionResult.url) {
  return {
  createdSessionId: null,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,
@@ -102,7 +102,7 @@ export function useSSO() {
 
  return {
  createdSessionId: signUp.createdSessionId ?? signIn.createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,

.changeset/split-setactive-into-select-methods.md

@@ -0,0 +1,92 @@
+---
+'@clerk/clerk-js': major
+'@clerk/shared': major
+'@clerk/react': major
+'@clerk/nextjs': major
+'@clerk/vue': major
+'@clerk/expo': major
+'@clerk/ui': major
+'@clerk/testing': major
+---
+
+Replace `setActive` with purpose-specific methods: `selectSession` and `selectOrganization`
+
+## Breaking Changes
+
+### `setActive` Removed from Public API
+
+The `setActive` method has been removed from the Clerk object and all hooks. Use the new purpose-specific methods instead:
+
+- `clerk.selectSession(session, options?)` - For session selection
+- `clerk.selectOrganization(organization, options?)` - For organization selection
+
+### Hook Return Types
+
+The following hooks no longer return `setActive`:
+
+- `useSignIn()` - now returns `selectSession` instead of `setActive`
+- `useSignUp()` - now returns `selectSession` instead of `setActive`
+- `useSessionList()` - now returns `selectSession` instead of `setActive`
+- `useOrganizationList()` - now returns `selectOrganization` instead of `setActive`
+
+### Migration
+
+**Before:**
+```tsx
+const { setActive } = useSignIn();
+await setActive({ session: createdSessionId });
+
+const { setActive } = useOrganizationList();
+await setActive({ organization: org });
+```
+
+**After:**
+```tsx
+const { selectSession } = useSignIn();
+await selectSession(createdSessionId);
+
+const { selectOrganization } = useOrganizationList();
+await selectOrganization(org);
+```
+
+### New Methods on Clerk Object
+
+Two new methods are available on the Clerk object:
+
+- `clerk.selectSession(session, options?)` - For session selection (sign-in, sign-up, multi-session switching)
+- `clerk.selectOrganization(organization, options?)` - For organization selection (org switching, personal workspace)
+
+### Options
+
+Both methods accept an options object:
+
+```tsx
+// selectSession options
+await selectSession(session, {
+ redirectUrl?: string;
+ navigate?: ({ session }) => void | Promise<void>;
+});
+
+// selectOrganization options
+await selectOrganization(organization, {
+ redirectUrl?: string;
+ navigate?: ({ session, organization }) => void | Promise<void>;
+});
+```
+
+### Expo Hooks
+
+The `StartGoogleAuthenticationFlowReturnType` and `StartAppleAuthenticationFlowReturnType` types now return `selectSession` instead of `setActive`.
+
+### Internal Window Hooks (Next.js)
+
+The internal window hooks have been renamed:
+- `__internal_onBeforeSetActive` → `__internal_onBeforeSelectSession`
+- `__internal_onAfterSetActive` → `__internal_onAfterSelectSession`
+
+### Types Removed
+
+The following types have been removed from the public API:
+- `SetActive`
+- `SetActiveParams`
+- `SetActiveNavigate` (use `SelectSessionNavigate` instead)

packages/clerk-js/src/core/clerk.ts

@@ -97,6 +97,8 @@ import type {
  RedirectOptions,
  Resources,
  SDKMetadata,
+ SelectOrganizationOptions,
+ SelectSessionOptions,
  SessionResource,
  SetActiveParams,
  SignedInSessionResource,
@@ -297,7 +299,7 @@ export class Clerk implements ClerkInterface {
  public __internal_isWebAuthnAutofillSupported: (() => Promise<boolean>) | undefined;
  public __internal_isWebAuthnPlatformAuthenticatorSupported: (() => Promise<boolean>) | undefined;
 
- public __internal_setActiveInProgress = false;
+ public __internal_selectSessionInProgress = false;
 
  get publishableKey(): string {
  return this.#publishableKey;
@@ -583,13 +585,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  const opts = callbackOrOptions && typeof callbackOrOptions === 'object' ? callbackOrOptions : options || {};
@@ -1446,7 +1448,7 @@ export class Clerk implements ClerkInterface {
  public setActive = async (params: SetActiveParams): Promise<void> => {
  const { organization, redirectUrl, navigate: setActiveNavigate } = params;
  let { session } = params;
- this.__internal_setActiveInProgress = true;
+ this.__internal_selectSessionInProgress = true;
  debugLogger.debug(
  'setActive() start',
  {
@@ -1476,13 +1478,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  let newSession = session === undefined ? this.session : session;
@@ -1605,10 +1607,79 @@ export class Clerk implements ClerkInterface {
  await onAfterSetActive();
  }
  } finally {
- this.__internal_setActiveInProgress = false;
+ this.__internal_selectSessionInProgress = false;
  }
  };
 
+ /**
+ * Select a session to make active.
+ *
+ * Use this method after sign-in or sign-up to activate the created session,
+ * or to switch between sessions in a multi-session application.
+ *
+ * Pass `null` to sign out and clear the active session.
+ */
+ public selectSession = async (
+ session: SignedInSessionResource | string | null,
+ options?: SelectSessionOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session: s }: { session: SessionResource }) => {
+ const result = await navigate({ session: s });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ session,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
+ /**
+ * Select an organization to make active within the current session.
+ *
+ * Use this method to switch between organizations or to select a personal workspace.
+ *
+ * Pass `null` to switch to the personal workspace (no active organization).
+ */
+ public selectOrganization = async (
+ organization: OrganizationResource | string | null,
+ options?: SelectOrganizationOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session }: { session: SessionResource }) => {
+ // Resolve the organization for the callback
+ const org =
+ organization === null
+ ? null
+ : typeof organization === 'string'
+ ? (this.organization ?? null)
+ : organization;
+
+ const result = await navigate({ session, organization: org });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ organization,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
  public addListener = (listener: ListenerCallback): UnsubscribeCallback => {
  listener = memoizeListenerCallback(listener);
  this.#listeners.push(listener);
@@ -2596,8 +2667,8 @@ export class Clerk implements ClerkInterface {
  const hasTransitionedToPendingStatus = this.session.status === 'active' && session?.status === 'pending';
  if (hasTransitionedToPendingStatus) {
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  // Execute hooks to update server authentication context and trigger

packages/clerk-js/src/core/resources/BillingCheckout.ts

@@ -204,7 +204,7 @@ export class CheckoutFlow implements CheckoutFlowResourceNonStrict {
  throw new Error('Clerk: `confirm()` must be called before `finalize()`');
  }
 
- await BillingCheckout.clerk.setActive({ session: BillingCheckout.clerk.session?.id, navigate });
+ await BillingCheckout.clerk.selectSession(BillingCheckout.clerk.session?.id ?? null, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignIn.ts

@@ -1243,7 +1243,7 @@ class SignInFuture implements SignInFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignIn.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -972,7 +972,7 @@ class SignUpFuture implements SignUpFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignUp.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 }

packages/clerk-js/src/global.d.ts

@@ -15,8 +15,8 @@ const __BUILD_VARIANT_CHANNEL__: boolean;
 const __BUILD_VARIANT_CHIPS__: boolean;
 
 interface Window {
-__internal_onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
-__internal_onAfterSetActive: () => Promise<void> | void;
+__internal_onBeforeSelectSession: (intent?: 'sign-out') => Promise<void> | void;
+__internal_onAfterSelectSession: () => Promise<void> | void;
  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
  __internal_ClerkUiCtor?: import('@clerk/shared/types').ClerkUiConstructor;
  /**

packages/clerk-js/src/test/mock-helpers.ts

@@ -99,7 +99,8 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  });
 
  mockProp(clerkAny, 'navigate');
- mockProp(clerkAny, 'setActive');
+ mockProp(clerkAny, 'selectSession');
+ mockProp(clerkAny, 'selectOrganization');
  mockProp(clerkAny, 'redirectWithAuth');
  mockProp(clerkAny, '__internal_navigateWithError');
  return clerkAny as DeepVitestMocked<LoadedClerk>;

packages/expo/src/hooks/useOAuth.ts

@@ -1,5 +1,5 @@
 import { useSignIn, useSignUp } from '@clerk/react/legacy';
-import type { OAuthStrategy, SetActive, SignInResource, SignUpResource } from '@clerk/shared/types';
+import type { OAuthStrategy, SelectSessionHook, SignInResource, SignUpResource } from '@clerk/shared/types';
 import * as AuthSession from 'expo-auth-session';
 import * as WebBrowser from 'expo-web-browser';
 
@@ -18,7 +18,7 @@ export type StartOAuthFlowParams = {
 
 export type StartOAuthFlowReturnType = {
  createdSessionId: string;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
  authSessionResult?: WebBrowser.WebBrowserAuthSessionResult;
@@ -33,7 +33,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return errorThrower.throw('Missing oauth strategy');
  }
 
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startOAuthFlow(startOAuthFlowParams?: StartOAuthFlowParams): Promise<StartOAuthFlowReturnType> {
@@ -42,7 +42,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  createdSessionId: '',
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -79,7 +79,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId: '',
-setActive,
+selectSession,
  signIn,
  signUp,
  };
@@ -108,7 +108,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  };

packages/expo/src/hooks/useSSO.ts

@@ -2,7 +2,7 @@ import { useSignIn, useSignUp } from '@clerk/react/legacy';
 import type {
  EnterpriseSSOStrategy,
  OAuthStrategy,
-SetActive,
+SelectSessionHook,
  SignInResource,
  SignUpResource,
 } from '@clerk/shared/types';
@@ -28,13 +28,13 @@ export type StartSSOFlowParams = {
 export type StartSSOFlowReturnType = {
  createdSessionId: string | null;
  authSessionResult: WebBrowser.WebBrowserAuthSessionResult | null;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
 };
 
 export function useSSO() {
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startSSOFlow(startSSOFlowParams: StartSSOFlowParams): Promise<StartSSOFlowReturnType> {
@@ -44,7 +44,7 @@ export function useSSO() {
  authSessionResult: null,
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -81,7 +81,7 @@ export function useSSO() {
  if (authSessionResult.type !== 'success' || !authSessionResult.url) {
  return {
  createdSessionId: null,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,
@@ -102,7 +102,7 @@ export function useSSO() {
 
  return {
  createdSessionId: signUp.createdSessionId ?? signIn.createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,

.changeset/split-setactive-into-select-methods.md

@@ -0,0 +1,92 @@
+---
+'@clerk/clerk-js': major
+'@clerk/shared': major
+'@clerk/react': major
+'@clerk/nextjs': major
+'@clerk/vue': major
+'@clerk/expo': major
+'@clerk/ui': major
+'@clerk/testing': major
+---
+
+Replace `setActive` with purpose-specific methods: `selectSession` and `selectOrganization`
+
+## Breaking Changes
+
+### `setActive` Removed from Public API
+
+The `setActive` method has been removed from the Clerk object and all hooks. Use the new purpose-specific methods instead:
+
+- `clerk.selectSession(session, options?)` - For session selection
+- `clerk.selectOrganization(organization, options?)` - For organization selection
+
+### Hook Return Types
+
+The following hooks no longer return `setActive`:
+
+- `useSignIn()` - now returns `selectSession` instead of `setActive`
+- `useSignUp()` - now returns `selectSession` instead of `setActive`
+- `useSessionList()` - now returns `selectSession` instead of `setActive`
+- `useOrganizationList()` - now returns `selectOrganization` instead of `setActive`
+
+### Migration
+
+**Before:**
+```tsx
+const { setActive } = useSignIn();
+await setActive({ session: createdSessionId });
+
+const { setActive } = useOrganizationList();
+await setActive({ organization: org });
+```
+
+**After:**
+```tsx
+const { selectSession } = useSignIn();
+await selectSession(createdSessionId);
+
+const { selectOrganization } = useOrganizationList();
+await selectOrganization(org);
+```
+
+### New Methods on Clerk Object
+
+Two new methods are available on the Clerk object:
+
+- `clerk.selectSession(session, options?)` - For session selection (sign-in, sign-up, multi-session switching)
+- `clerk.selectOrganization(organization, options?)` - For organization selection (org switching, personal workspace)
+
+### Options
+
+Both methods accept an options object:
+
+```tsx
+// selectSession options
+await selectSession(session, {
+ redirectUrl?: string;
+ navigate?: ({ session }) => void | Promise<void>;
+});
+
+// selectOrganization options
+await selectOrganization(organization, {
+ redirectUrl?: string;
+ navigate?: ({ session, organization }) => void | Promise<void>;
+});
+```
+
+### Expo Hooks
+
+The `StartGoogleAuthenticationFlowReturnType` and `StartAppleAuthenticationFlowReturnType` types now return `selectSession` instead of `setActive`.
+
+### Internal Window Hooks (Next.js)
+
+The internal window hooks have been renamed:
+- `__internal_onBeforeSetActive` → `__internal_onBeforeSelectSession`
+- `__internal_onAfterSetActive` → `__internal_onAfterSelectSession`
+
+### Types Removed
+
+The following types have been removed from the public API:
+- `SetActive`
+- `SetActiveParams`
+- `SetActiveNavigate` (use `SelectSessionNavigate` instead)

packages/clerk-js/src/core/clerk.ts

@@ -97,6 +97,8 @@ import type {
  RedirectOptions,
  Resources,
  SDKMetadata,
+ SelectOrganizationOptions,
+ SelectSessionOptions,
  SessionResource,
  SetActiveParams,
  SignedInSessionResource,
@@ -297,7 +299,7 @@ export class Clerk implements ClerkInterface {
  public __internal_isWebAuthnAutofillSupported: (() => Promise<boolean>) | undefined;
  public __internal_isWebAuthnPlatformAuthenticatorSupported: (() => Promise<boolean>) | undefined;
 
- public __internal_setActiveInProgress = false;
+ public __internal_selectSessionInProgress = false;
 
  get publishableKey(): string {
  return this.#publishableKey;
@@ -583,13 +585,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  const opts = callbackOrOptions && typeof callbackOrOptions === 'object' ? callbackOrOptions : options || {};
@@ -1446,7 +1448,7 @@ export class Clerk implements ClerkInterface {
  public setActive = async (params: SetActiveParams): Promise<void> => {
  const { organization, redirectUrl, navigate: setActiveNavigate } = params;
  let { session } = params;
- this.__internal_setActiveInProgress = true;
+ this.__internal_selectSessionInProgress = true;
  debugLogger.debug(
  'setActive() start',
  {
@@ -1476,13 +1478,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  let newSession = session === undefined ? this.session : session;
@@ -1605,10 +1607,79 @@ export class Clerk implements ClerkInterface {
  await onAfterSetActive();
  }
  } finally {
- this.__internal_setActiveInProgress = false;
+ this.__internal_selectSessionInProgress = false;
  }
  };
 
+ /**
+ * Select a session to make active.
+ *
+ * Use this method after sign-in or sign-up to activate the created session,
+ * or to switch between sessions in a multi-session application.
+ *
+ * Pass `null` to sign out and clear the active session.
+ */
+ public selectSession = async (
+ session: SignedInSessionResource | string | null,
+ options?: SelectSessionOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session: s }: { session: SessionResource }) => {
+ const result = await navigate({ session: s });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ session,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
+ /**
+ * Select an organization to make active within the current session.
+ *
+ * Use this method to switch between organizations or to select a personal workspace.
+ *
+ * Pass `null` to switch to the personal workspace (no active organization).
+ */
+ public selectOrganization = async (
+ organization: OrganizationResource | string | null,
+ options?: SelectOrganizationOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session }: { session: SessionResource }) => {
+ // Resolve the organization for the callback
+ const org =
+ organization === null
+ ? null
+ : typeof organization === 'string'
+ ? (this.organization ?? null)
+ : organization;
+
+ const result = await navigate({ session, organization: org });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ organization,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
  public addListener = (listener: ListenerCallback): UnsubscribeCallback => {
  listener = memoizeListenerCallback(listener);
  this.#listeners.push(listener);
@@ -2596,8 +2667,8 @@ export class Clerk implements ClerkInterface {
  const hasTransitionedToPendingStatus = this.session.status === 'active' && session?.status === 'pending';
  if (hasTransitionedToPendingStatus) {
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  // Execute hooks to update server authentication context and trigger

packages/clerk-js/src/core/resources/BillingCheckout.ts

@@ -204,7 +204,7 @@ export class CheckoutFlow implements CheckoutFlowResourceNonStrict {
  throw new Error('Clerk: `confirm()` must be called before `finalize()`');
  }
 
- await BillingCheckout.clerk.setActive({ session: BillingCheckout.clerk.session?.id, navigate });
+ await BillingCheckout.clerk.selectSession(BillingCheckout.clerk.session?.id ?? null, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignIn.ts

@@ -1243,7 +1243,7 @@ class SignInFuture implements SignInFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignIn.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -972,7 +972,7 @@ class SignUpFuture implements SignUpFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignUp.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 }

packages/clerk-js/src/global.d.ts

@@ -15,8 +15,8 @@ const __BUILD_VARIANT_CHANNEL__: boolean;
 const __BUILD_VARIANT_CHIPS__: boolean;
 
 interface Window {
-__internal_onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
-__internal_onAfterSetActive: () => Promise<void> | void;
+__internal_onBeforeSelectSession: (intent?: 'sign-out') => Promise<void> | void;
+__internal_onAfterSelectSession: () => Promise<void> | void;
  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
  __internal_ClerkUiCtor?: import('@clerk/shared/types').ClerkUiConstructor;
  /**

packages/clerk-js/src/test/mock-helpers.ts

@@ -99,7 +99,8 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  });
 
  mockProp(clerkAny, 'navigate');
- mockProp(clerkAny, 'setActive');
+ mockProp(clerkAny, 'selectSession');
+ mockProp(clerkAny, 'selectOrganization');
  mockProp(clerkAny, 'redirectWithAuth');
  mockProp(clerkAny, '__internal_navigateWithError');
  return clerkAny as DeepVitestMocked<LoadedClerk>;

packages/expo/src/hooks/useOAuth.ts

@@ -1,5 +1,5 @@
 import { useSignIn, useSignUp } from '@clerk/react/legacy';
-import type { OAuthStrategy, SetActive, SignInResource, SignUpResource } from '@clerk/shared/types';
+import type { OAuthStrategy, SelectSessionHook, SignInResource, SignUpResource } from '@clerk/shared/types';
 import * as AuthSession from 'expo-auth-session';
 import * as WebBrowser from 'expo-web-browser';
 
@@ -18,7 +18,7 @@ export type StartOAuthFlowParams = {
 
 export type StartOAuthFlowReturnType = {
  createdSessionId: string;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
  authSessionResult?: WebBrowser.WebBrowserAuthSessionResult;
@@ -33,7 +33,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return errorThrower.throw('Missing oauth strategy');
  }
 
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startOAuthFlow(startOAuthFlowParams?: StartOAuthFlowParams): Promise<StartOAuthFlowReturnType> {
@@ -42,7 +42,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  createdSessionId: '',
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -79,7 +79,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId: '',
-setActive,
+selectSession,
  signIn,
  signUp,
  };
@@ -108,7 +108,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  };

packages/expo/src/hooks/useSSO.ts

@@ -2,7 +2,7 @@ import { useSignIn, useSignUp } from '@clerk/react/legacy';
 import type {
  EnterpriseSSOStrategy,
  OAuthStrategy,
-SetActive,
+SelectSessionHook,
  SignInResource,
  SignUpResource,
 } from '@clerk/shared/types';
@@ -28,13 +28,13 @@ export type StartSSOFlowParams = {
 export type StartSSOFlowReturnType = {
  createdSessionId: string | null;
  authSessionResult: WebBrowser.WebBrowserAuthSessionResult | null;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
 };
 
 export function useSSO() {
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startSSOFlow(startSSOFlowParams: StartSSOFlowParams): Promise<StartSSOFlowReturnType> {
@@ -44,7 +44,7 @@ export function useSSO() {
  authSessionResult: null,
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -81,7 +81,7 @@ export function useSSO() {
  if (authSessionResult.type !== 'success' || !authSessionResult.url) {
  return {
  createdSessionId: null,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,
@@ -102,7 +102,7 @@ export function useSSO() {
 
  return {
  createdSessionId: signUp.createdSessionId ?? signIn.createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,

.changeset/split-setactive-into-select-methods.md

@@ -0,0 +1,92 @@
+---
+'@clerk/clerk-js': major
+'@clerk/shared': major
+'@clerk/react': major
+'@clerk/nextjs': major
+'@clerk/vue': major
+'@clerk/expo': major
+'@clerk/ui': major
+'@clerk/testing': major
+---
+
+Replace `setActive` with purpose-specific methods: `selectSession` and `selectOrganization`
+
+## Breaking Changes
+
+### `setActive` Removed from Public API
+
+The `setActive` method has been removed from the Clerk object and all hooks. Use the new purpose-specific methods instead:
+
+- `clerk.selectSession(session, options?)` - For session selection
+- `clerk.selectOrganization(organization, options?)` - For organization selection
+
+### Hook Return Types
+
+The following hooks no longer return `setActive`:
+
+- `useSignIn()` - now returns `selectSession` instead of `setActive`
+- `useSignUp()` - now returns `selectSession` instead of `setActive`
+- `useSessionList()` - now returns `selectSession` instead of `setActive`
+- `useOrganizationList()` - now returns `selectOrganization` instead of `setActive`
+
+### Migration
+
+**Before:**
+```tsx
+const { setActive } = useSignIn();
+await setActive({ session: createdSessionId });
+
+const { setActive } = useOrganizationList();
+await setActive({ organization: org });
+```
+
+**After:**
+```tsx
+const { selectSession } = useSignIn();
+await selectSession(createdSessionId);
+
+const { selectOrganization } = useOrganizationList();
+await selectOrganization(org);
+```
+
+### New Methods on Clerk Object
+
+Two new methods are available on the Clerk object:
+
+- `clerk.selectSession(session, options?)` - For session selection (sign-in, sign-up, multi-session switching)
+- `clerk.selectOrganization(organization, options?)` - For organization selection (org switching, personal workspace)
+
+### Options
+
+Both methods accept an options object:
+
+```tsx
+// selectSession options
+await selectSession(session, {
+ redirectUrl?: string;
+ navigate?: ({ session }) => void | Promise<void>;
+});
+
+// selectOrganization options
+await selectOrganization(organization, {
+ redirectUrl?: string;
+ navigate?: ({ session, organization }) => void | Promise<void>;
+});
+```
+
+### Expo Hooks
+
+The `StartGoogleAuthenticationFlowReturnType` and `StartAppleAuthenticationFlowReturnType` types now return `selectSession` instead of `setActive`.
+
+### Internal Window Hooks (Next.js)
+
+The internal window hooks have been renamed:
+- `__internal_onBeforeSetActive` → `__internal_onBeforeSelectSession`
+- `__internal_onAfterSetActive` → `__internal_onAfterSelectSession`
+
+### Types Removed
+
+The following types have been removed from the public API:
+- `SetActive`
+- `SetActiveParams`
+- `SetActiveNavigate` (use `SelectSessionNavigate` instead)

packages/clerk-js/src/core/clerk.ts

@@ -97,6 +97,8 @@ import type {
  RedirectOptions,
  Resources,
  SDKMetadata,
+ SelectOrganizationOptions,
+ SelectSessionOptions,
  SessionResource,
  SetActiveParams,
  SignedInSessionResource,
@@ -297,7 +299,7 @@ export class Clerk implements ClerkInterface {
  public __internal_isWebAuthnAutofillSupported: (() => Promise<boolean>) | undefined;
  public __internal_isWebAuthnPlatformAuthenticatorSupported: (() => Promise<boolean>) | undefined;
 
- public __internal_setActiveInProgress = false;
+ public __internal_selectSessionInProgress = false;
 
  get publishableKey(): string {
  return this.#publishableKey;
@@ -583,13 +585,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  const opts = callbackOrOptions && typeof callbackOrOptions === 'object' ? callbackOrOptions : options || {};
@@ -1446,7 +1448,7 @@ export class Clerk implements ClerkInterface {
  public setActive = async (params: SetActiveParams): Promise<void> => {
  const { organization, redirectUrl, navigate: setActiveNavigate } = params;
  let { session } = params;
- this.__internal_setActiveInProgress = true;
+ this.__internal_selectSessionInProgress = true;
  debugLogger.debug(
  'setActive() start',
  {
@@ -1476,13 +1478,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  let newSession = session === undefined ? this.session : session;
@@ -1605,10 +1607,79 @@ export class Clerk implements ClerkInterface {
  await onAfterSetActive();
  }
  } finally {
- this.__internal_setActiveInProgress = false;
+ this.__internal_selectSessionInProgress = false;
  }
  };
 
+ /**
+ * Select a session to make active.
+ *
+ * Use this method after sign-in or sign-up to activate the created session,
+ * or to switch between sessions in a multi-session application.
+ *
+ * Pass `null` to sign out and clear the active session.
+ */
+ public selectSession = async (
+ session: SignedInSessionResource | string | null,
+ options?: SelectSessionOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session: s }: { session: SessionResource }) => {
+ const result = await navigate({ session: s });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ session,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
+ /**
+ * Select an organization to make active within the current session.
+ *
+ * Use this method to switch between organizations or to select a personal workspace.
+ *
+ * Pass `null` to switch to the personal workspace (no active organization).
+ */
+ public selectOrganization = async (
+ organization: OrganizationResource | string | null,
+ options?: SelectOrganizationOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session }: { session: SessionResource }) => {
+ // Resolve the organization for the callback
+ const org =
+ organization === null
+ ? null
+ : typeof organization === 'string'
+ ? (this.organization ?? null)
+ : organization;
+
+ const result = await navigate({ session, organization: org });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ organization,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
  public addListener = (listener: ListenerCallback): UnsubscribeCallback => {
  listener = memoizeListenerCallback(listener);
  this.#listeners.push(listener);
@@ -2596,8 +2667,8 @@ export class Clerk implements ClerkInterface {
  const hasTransitionedToPendingStatus = this.session.status === 'active' && session?.status === 'pending';
  if (hasTransitionedToPendingStatus) {
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  // Execute hooks to update server authentication context and trigger

packages/clerk-js/src/core/resources/BillingCheckout.ts

@@ -204,7 +204,7 @@ export class CheckoutFlow implements CheckoutFlowResourceNonStrict {
  throw new Error('Clerk: `confirm()` must be called before `finalize()`');
  }
 
- await BillingCheckout.clerk.setActive({ session: BillingCheckout.clerk.session?.id, navigate });
+ await BillingCheckout.clerk.selectSession(BillingCheckout.clerk.session?.id ?? null, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignIn.ts

@@ -1243,7 +1243,7 @@ class SignInFuture implements SignInFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignIn.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -972,7 +972,7 @@ class SignUpFuture implements SignUpFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignUp.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 }

packages/clerk-js/src/global.d.ts

@@ -15,8 +15,8 @@ const __BUILD_VARIANT_CHANNEL__: boolean;
 const __BUILD_VARIANT_CHIPS__: boolean;
 
 interface Window {
-__internal_onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
-__internal_onAfterSetActive: () => Promise<void> | void;
+__internal_onBeforeSelectSession: (intent?: 'sign-out') => Promise<void> | void;
+__internal_onAfterSelectSession: () => Promise<void> | void;
  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
  __internal_ClerkUiCtor?: import('@clerk/shared/types').ClerkUiConstructor;
  /**

packages/clerk-js/src/test/mock-helpers.ts

@@ -99,7 +99,8 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  });
 
  mockProp(clerkAny, 'navigate');
- mockProp(clerkAny, 'setActive');
+ mockProp(clerkAny, 'selectSession');
+ mockProp(clerkAny, 'selectOrganization');
  mockProp(clerkAny, 'redirectWithAuth');
  mockProp(clerkAny, '__internal_navigateWithError');
  return clerkAny as DeepVitestMocked<LoadedClerk>;

packages/expo/src/hooks/useOAuth.ts

@@ -1,5 +1,5 @@
 import { useSignIn, useSignUp } from '@clerk/react/legacy';
-import type { OAuthStrategy, SetActive, SignInResource, SignUpResource } from '@clerk/shared/types';
+import type { OAuthStrategy, SelectSessionHook, SignInResource, SignUpResource } from '@clerk/shared/types';
 import * as AuthSession from 'expo-auth-session';
 import * as WebBrowser from 'expo-web-browser';
 
@@ -18,7 +18,7 @@ export type StartOAuthFlowParams = {
 
 export type StartOAuthFlowReturnType = {
  createdSessionId: string;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
  authSessionResult?: WebBrowser.WebBrowserAuthSessionResult;
@@ -33,7 +33,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return errorThrower.throw('Missing oauth strategy');
  }
 
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startOAuthFlow(startOAuthFlowParams?: StartOAuthFlowParams): Promise<StartOAuthFlowReturnType> {
@@ -42,7 +42,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  createdSessionId: '',
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -79,7 +79,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId: '',
-setActive,
+selectSession,
  signIn,
  signUp,
  };
@@ -108,7 +108,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  };

packages/expo/src/hooks/useSSO.ts

@@ -2,7 +2,7 @@ import { useSignIn, useSignUp } from '@clerk/react/legacy';
 import type {
  EnterpriseSSOStrategy,
  OAuthStrategy,
-SetActive,
+SelectSessionHook,
  SignInResource,
  SignUpResource,
 } from '@clerk/shared/types';
@@ -28,13 +28,13 @@ export type StartSSOFlowParams = {
 export type StartSSOFlowReturnType = {
  createdSessionId: string | null;
  authSessionResult: WebBrowser.WebBrowserAuthSessionResult | null;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
 };
 
 export function useSSO() {
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startSSOFlow(startSSOFlowParams: StartSSOFlowParams): Promise<StartSSOFlowReturnType> {
@@ -44,7 +44,7 @@ export function useSSO() {
  authSessionResult: null,
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -81,7 +81,7 @@ export function useSSO() {
  if (authSessionResult.type !== 'success' || !authSessionResult.url) {
  return {
  createdSessionId: null,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,
@@ -102,7 +102,7 @@ export function useSSO() {
 
  return {
  createdSessionId: signUp.createdSessionId ?? signIn.createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,

.changeset/split-setactive-into-select-methods.md

@@ -0,0 +1,92 @@
+---
+'@clerk/clerk-js': major
+'@clerk/shared': major
+'@clerk/react': major
+'@clerk/nextjs': major
+'@clerk/vue': major
+'@clerk/expo': major
+'@clerk/ui': major
+'@clerk/testing': major
+---
+
+Replace `setActive` with purpose-specific methods: `selectSession` and `selectOrganization`
+
+## Breaking Changes
+
+### `setActive` Removed from Public API
+
+The `setActive` method has been removed from the Clerk object and all hooks. Use the new purpose-specific methods instead:
+
+- `clerk.selectSession(session, options?)` - For session selection
+- `clerk.selectOrganization(organization, options?)` - For organization selection
+
+### Hook Return Types
+
+The following hooks no longer return `setActive`:
+
+- `useSignIn()` - now returns `selectSession` instead of `setActive`
+- `useSignUp()` - now returns `selectSession` instead of `setActive`
+- `useSessionList()` - now returns `selectSession` instead of `setActive`
+- `useOrganizationList()` - now returns `selectOrganization` instead of `setActive`
+
+### Migration
+
+**Before:**
+```tsx
+const { setActive } = useSignIn();
+await setActive({ session: createdSessionId });
+
+const { setActive } = useOrganizationList();
+await setActive({ organization: org });
+```
+
+**After:**
+```tsx
+const { selectSession } = useSignIn();
+await selectSession(createdSessionId);
+
+const { selectOrganization } = useOrganizationList();
+await selectOrganization(org);
+```
+
+### New Methods on Clerk Object
+
+Two new methods are available on the Clerk object:
+
+- `clerk.selectSession(session, options?)` - For session selection (sign-in, sign-up, multi-session switching)
+- `clerk.selectOrganization(organization, options?)` - For organization selection (org switching, personal workspace)
+
+### Options
+
+Both methods accept an options object:
+
+```tsx
+// selectSession options
+await selectSession(session, {
+ redirectUrl?: string;
+ navigate?: ({ session }) => void | Promise<void>;
+});
+
+// selectOrganization options
+await selectOrganization(organization, {
+ redirectUrl?: string;
+ navigate?: ({ session, organization }) => void | Promise<void>;
+});
+```
+
+### Expo Hooks
+
+The `StartGoogleAuthenticationFlowReturnType` and `StartAppleAuthenticationFlowReturnType` types now return `selectSession` instead of `setActive`.
+
+### Internal Window Hooks (Next.js)
+
+The internal window hooks have been renamed:
+- `__internal_onBeforeSetActive` → `__internal_onBeforeSelectSession`
+- `__internal_onAfterSetActive` → `__internal_onAfterSelectSession`
+
+### Types Removed
+
+The following types have been removed from the public API:
+- `SetActive`
+- `SetActiveParams`
+- `SetActiveNavigate` (use `SelectSessionNavigate` instead)

packages/clerk-js/src/core/clerk.ts

@@ -97,6 +97,8 @@ import type {
  RedirectOptions,
  Resources,
  SDKMetadata,
+ SelectOrganizationOptions,
+ SelectSessionOptions,
  SessionResource,
  SetActiveParams,
  SignedInSessionResource,
@@ -297,7 +299,7 @@ export class Clerk implements ClerkInterface {
  public __internal_isWebAuthnAutofillSupported: (() => Promise<boolean>) | undefined;
  public __internal_isWebAuthnPlatformAuthenticatorSupported: (() => Promise<boolean>) | undefined;
 
- public __internal_setActiveInProgress = false;
+ public __internal_selectSessionInProgress = false;
 
  get publishableKey(): string {
  return this.#publishableKey;
@@ -583,13 +585,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  const opts = callbackOrOptions && typeof callbackOrOptions === 'object' ? callbackOrOptions : options || {};
@@ -1446,7 +1448,7 @@ export class Clerk implements ClerkInterface {
  public setActive = async (params: SetActiveParams): Promise<void> => {
  const { organization, redirectUrl, navigate: setActiveNavigate } = params;
  let { session } = params;
- this.__internal_setActiveInProgress = true;
+ this.__internal_selectSessionInProgress = true;
  debugLogger.debug(
  'setActive() start',
  {
@@ -1476,13 +1478,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  let newSession = session === undefined ? this.session : session;
@@ -1605,10 +1607,79 @@ export class Clerk implements ClerkInterface {
  await onAfterSetActive();
  }
  } finally {
- this.__internal_setActiveInProgress = false;
+ this.__internal_selectSessionInProgress = false;
  }
  };
 
+ /**
+ * Select a session to make active.
+ *
+ * Use this method after sign-in or sign-up to activate the created session,
+ * or to switch between sessions in a multi-session application.
+ *
+ * Pass `null` to sign out and clear the active session.
+ */
+ public selectSession = async (
+ session: SignedInSessionResource | string | null,
+ options?: SelectSessionOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session: s }: { session: SessionResource }) => {
+ const result = await navigate({ session: s });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ session,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
+ /**
+ * Select an organization to make active within the current session.
+ *
+ * Use this method to switch between organizations or to select a personal workspace.
+ *
+ * Pass `null` to switch to the personal workspace (no active organization).
+ */
+ public selectOrganization = async (
+ organization: OrganizationResource | string | null,
+ options?: SelectOrganizationOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session }: { session: SessionResource }) => {
+ // Resolve the organization for the callback
+ const org =
+ organization === null
+ ? null
+ : typeof organization === 'string'
+ ? (this.organization ?? null)
+ : organization;
+
+ const result = await navigate({ session, organization: org });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ organization,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
  public addListener = (listener: ListenerCallback): UnsubscribeCallback => {
  listener = memoizeListenerCallback(listener);
  this.#listeners.push(listener);
@@ -2596,8 +2667,8 @@ export class Clerk implements ClerkInterface {
  const hasTransitionedToPendingStatus = this.session.status === 'active' && session?.status === 'pending';
  if (hasTransitionedToPendingStatus) {
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  // Execute hooks to update server authentication context and trigger

packages/clerk-js/src/core/resources/BillingCheckout.ts

@@ -204,7 +204,7 @@ export class CheckoutFlow implements CheckoutFlowResourceNonStrict {
  throw new Error('Clerk: `confirm()` must be called before `finalize()`');
  }
 
- await BillingCheckout.clerk.setActive({ session: BillingCheckout.clerk.session?.id, navigate });
+ await BillingCheckout.clerk.selectSession(BillingCheckout.clerk.session?.id ?? null, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignIn.ts

@@ -1243,7 +1243,7 @@ class SignInFuture implements SignInFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignIn.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -972,7 +972,7 @@ class SignUpFuture implements SignUpFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignUp.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 }

packages/clerk-js/src/global.d.ts

@@ -15,8 +15,8 @@ const __BUILD_VARIANT_CHANNEL__: boolean;
 const __BUILD_VARIANT_CHIPS__: boolean;
 
 interface Window {
-__internal_onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
-__internal_onAfterSetActive: () => Promise<void> | void;
+__internal_onBeforeSelectSession: (intent?: 'sign-out') => Promise<void> | void;
+__internal_onAfterSelectSession: () => Promise<void> | void;
  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
  __internal_ClerkUiCtor?: import('@clerk/shared/types').ClerkUiConstructor;
  /**

packages/clerk-js/src/test/mock-helpers.ts

@@ -99,7 +99,8 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  });
 
  mockProp(clerkAny, 'navigate');
- mockProp(clerkAny, 'setActive');
+ mockProp(clerkAny, 'selectSession');
+ mockProp(clerkAny, 'selectOrganization');
  mockProp(clerkAny, 'redirectWithAuth');
  mockProp(clerkAny, '__internal_navigateWithError');
  return clerkAny as DeepVitestMocked<LoadedClerk>;

packages/expo/src/hooks/useOAuth.ts

@@ -1,5 +1,5 @@
 import { useSignIn, useSignUp } from '@clerk/react/legacy';
-import type { OAuthStrategy, SetActive, SignInResource, SignUpResource } from '@clerk/shared/types';
+import type { OAuthStrategy, SelectSessionHook, SignInResource, SignUpResource } from '@clerk/shared/types';
 import * as AuthSession from 'expo-auth-session';
 import * as WebBrowser from 'expo-web-browser';
 
@@ -18,7 +18,7 @@ export type StartOAuthFlowParams = {
 
 export type StartOAuthFlowReturnType = {
  createdSessionId: string;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
  authSessionResult?: WebBrowser.WebBrowserAuthSessionResult;
@@ -33,7 +33,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return errorThrower.throw('Missing oauth strategy');
  }
 
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startOAuthFlow(startOAuthFlowParams?: StartOAuthFlowParams): Promise<StartOAuthFlowReturnType> {
@@ -42,7 +42,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  createdSessionId: '',
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -79,7 +79,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId: '',
-setActive,
+selectSession,
  signIn,
  signUp,
  };
@@ -108,7 +108,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  };

packages/expo/src/hooks/useSSO.ts

@@ -2,7 +2,7 @@ import { useSignIn, useSignUp } from '@clerk/react/legacy';
 import type {
  EnterpriseSSOStrategy,
  OAuthStrategy,
-SetActive,
+SelectSessionHook,
  SignInResource,
  SignUpResource,
 } from '@clerk/shared/types';
@@ -28,13 +28,13 @@ export type StartSSOFlowParams = {
 export type StartSSOFlowReturnType = {
  createdSessionId: string | null;
  authSessionResult: WebBrowser.WebBrowserAuthSessionResult | null;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
 };
 
 export function useSSO() {
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startSSOFlow(startSSOFlowParams: StartSSOFlowParams): Promise<StartSSOFlowReturnType> {
@@ -44,7 +44,7 @@ export function useSSO() {
  authSessionResult: null,
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -81,7 +81,7 @@ export function useSSO() {
  if (authSessionResult.type !== 'success' || !authSessionResult.url) {
  return {
  createdSessionId: null,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,
@@ -102,7 +102,7 @@ export function useSSO() {
 
  return {
  createdSessionId: signUp.createdSessionId ?? signIn.createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,

.changeset/split-setactive-into-select-methods.md

@@ -0,0 +1,92 @@
+---
+'@clerk/clerk-js': major
+'@clerk/shared': major
+'@clerk/react': major
+'@clerk/nextjs': major
+'@clerk/vue': major
+'@clerk/expo': major
+'@clerk/ui': major
+'@clerk/testing': major
+---
+
+Replace `setActive` with purpose-specific methods: `selectSession` and `selectOrganization`
+
+## Breaking Changes
+
+### `setActive` Removed from Public API
+
+The `setActive` method has been removed from the Clerk object and all hooks. Use the new purpose-specific methods instead:
+
+- `clerk.selectSession(session, options?)` - For session selection
+- `clerk.selectOrganization(organization, options?)` - For organization selection
+
+### Hook Return Types
+
+The following hooks no longer return `setActive`:
+
+- `useSignIn()` - now returns `selectSession` instead of `setActive`
+- `useSignUp()` - now returns `selectSession` instead of `setActive`
+- `useSessionList()` - now returns `selectSession` instead of `setActive`
+- `useOrganizationList()` - now returns `selectOrganization` instead of `setActive`
+
+### Migration
+
+**Before:**
+```tsx
+const { setActive } = useSignIn();
+await setActive({ session: createdSessionId });
+
+const { setActive } = useOrganizationList();
+await setActive({ organization: org });
+```
+
+**After:**
+```tsx
+const { selectSession } = useSignIn();
+await selectSession(createdSessionId);
+
+const { selectOrganization } = useOrganizationList();
+await selectOrganization(org);
+```
+
+### New Methods on Clerk Object
+
+Two new methods are available on the Clerk object:
+
+- `clerk.selectSession(session, options?)` - For session selection (sign-in, sign-up, multi-session switching)
+- `clerk.selectOrganization(organization, options?)` - For organization selection (org switching, personal workspace)
+
+### Options
+
+Both methods accept an options object:
+
+```tsx
+// selectSession options
+await selectSession(session, {
+ redirectUrl?: string;
+ navigate?: ({ session }) => void | Promise<void>;
+});
+
+// selectOrganization options
+await selectOrganization(organization, {
+ redirectUrl?: string;
+ navigate?: ({ session, organization }) => void | Promise<void>;
+});
+```
+
+### Expo Hooks
+
+The `StartGoogleAuthenticationFlowReturnType` and `StartAppleAuthenticationFlowReturnType` types now return `selectSession` instead of `setActive`.
+
+### Internal Window Hooks (Next.js)
+
+The internal window hooks have been renamed:
+- `__internal_onBeforeSetActive` → `__internal_onBeforeSelectSession`
+- `__internal_onAfterSetActive` → `__internal_onAfterSelectSession`
+
+### Types Removed
+
+The following types have been removed from the public API:
+- `SetActive`
+- `SetActiveParams`
+- `SetActiveNavigate` (use `SelectSessionNavigate` instead)

packages/clerk-js/src/core/clerk.ts

@@ -97,6 +97,8 @@ import type {
  RedirectOptions,
  Resources,
  SDKMetadata,
+ SelectOrganizationOptions,
+ SelectSessionOptions,
  SessionResource,
  SetActiveParams,
  SignedInSessionResource,
@@ -297,7 +299,7 @@ export class Clerk implements ClerkInterface {
  public __internal_isWebAuthnAutofillSupported: (() => Promise<boolean>) | undefined;
  public __internal_isWebAuthnPlatformAuthenticatorSupported: (() => Promise<boolean>) | undefined;
 
- public __internal_setActiveInProgress = false;
+ public __internal_selectSessionInProgress = false;
 
  get publishableKey(): string {
  return this.#publishableKey;
@@ -583,13 +585,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  const opts = callbackOrOptions && typeof callbackOrOptions === 'object' ? callbackOrOptions : options || {};
@@ -1446,7 +1448,7 @@ export class Clerk implements ClerkInterface {
  public setActive = async (params: SetActiveParams): Promise<void> => {
  const { organization, redirectUrl, navigate: setActiveNavigate } = params;
  let { session } = params;
- this.__internal_setActiveInProgress = true;
+ this.__internal_selectSessionInProgress = true;
  debugLogger.debug(
  'setActive() start',
  {
@@ -1476,13 +1478,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  let newSession = session === undefined ? this.session : session;
@@ -1605,10 +1607,79 @@ export class Clerk implements ClerkInterface {
  await onAfterSetActive();
  }
  } finally {
- this.__internal_setActiveInProgress = false;
+ this.__internal_selectSessionInProgress = false;
  }
  };
 
+ /**
+ * Select a session to make active.
+ *
+ * Use this method after sign-in or sign-up to activate the created session,
+ * or to switch between sessions in a multi-session application.
+ *
+ * Pass `null` to sign out and clear the active session.
+ */
+ public selectSession = async (
+ session: SignedInSessionResource | string | null,
+ options?: SelectSessionOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session: s }: { session: SessionResource }) => {
+ const result = await navigate({ session: s });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ session,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
+ /**
+ * Select an organization to make active within the current session.
+ *
+ * Use this method to switch between organizations or to select a personal workspace.
+ *
+ * Pass `null` to switch to the personal workspace (no active organization).
+ */
+ public selectOrganization = async (
+ organization: OrganizationResource | string | null,
+ options?: SelectOrganizationOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session }: { session: SessionResource }) => {
+ // Resolve the organization for the callback
+ const org =
+ organization === null
+ ? null
+ : typeof organization === 'string'
+ ? (this.organization ?? null)
+ : organization;
+
+ const result = await navigate({ session, organization: org });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ organization,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
  public addListener = (listener: ListenerCallback): UnsubscribeCallback => {
  listener = memoizeListenerCallback(listener);
  this.#listeners.push(listener);
@@ -2596,8 +2667,8 @@ export class Clerk implements ClerkInterface {
  const hasTransitionedToPendingStatus = this.session.status === 'active' && session?.status === 'pending';
  if (hasTransitionedToPendingStatus) {
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  // Execute hooks to update server authentication context and trigger

packages/clerk-js/src/core/resources/BillingCheckout.ts

@@ -204,7 +204,7 @@ export class CheckoutFlow implements CheckoutFlowResourceNonStrict {
  throw new Error('Clerk: `confirm()` must be called before `finalize()`');
  }
 
- await BillingCheckout.clerk.setActive({ session: BillingCheckout.clerk.session?.id, navigate });
+ await BillingCheckout.clerk.selectSession(BillingCheckout.clerk.session?.id ?? null, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignIn.ts

@@ -1243,7 +1243,7 @@ class SignInFuture implements SignInFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignIn.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -972,7 +972,7 @@ class SignUpFuture implements SignUpFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignUp.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 }

packages/clerk-js/src/global.d.ts

@@ -15,8 +15,8 @@ const __BUILD_VARIANT_CHANNEL__: boolean;
 const __BUILD_VARIANT_CHIPS__: boolean;
 
 interface Window {
-__internal_onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
-__internal_onAfterSetActive: () => Promise<void> | void;
+__internal_onBeforeSelectSession: (intent?: 'sign-out') => Promise<void> | void;
+__internal_onAfterSelectSession: () => Promise<void> | void;
  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
  __internal_ClerkUiCtor?: import('@clerk/shared/types').ClerkUiConstructor;
  /**

packages/clerk-js/src/test/mock-helpers.ts

@@ -99,7 +99,8 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  });
 
  mockProp(clerkAny, 'navigate');
- mockProp(clerkAny, 'setActive');
+ mockProp(clerkAny, 'selectSession');
+ mockProp(clerkAny, 'selectOrganization');
  mockProp(clerkAny, 'redirectWithAuth');
  mockProp(clerkAny, '__internal_navigateWithError');
  return clerkAny as DeepVitestMocked<LoadedClerk>;

packages/expo/src/hooks/useOAuth.ts

@@ -1,5 +1,5 @@
 import { useSignIn, useSignUp } from '@clerk/react/legacy';
-import type { OAuthStrategy, SetActive, SignInResource, SignUpResource } from '@clerk/shared/types';
+import type { OAuthStrategy, SelectSessionHook, SignInResource, SignUpResource } from '@clerk/shared/types';
 import * as AuthSession from 'expo-auth-session';
 import * as WebBrowser from 'expo-web-browser';
 
@@ -18,7 +18,7 @@ export type StartOAuthFlowParams = {
 
 export type StartOAuthFlowReturnType = {
  createdSessionId: string;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
  authSessionResult?: WebBrowser.WebBrowserAuthSessionResult;
@@ -33,7 +33,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return errorThrower.throw('Missing oauth strategy');
  }
 
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startOAuthFlow(startOAuthFlowParams?: StartOAuthFlowParams): Promise<StartOAuthFlowReturnType> {
@@ -42,7 +42,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  createdSessionId: '',
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -79,7 +79,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId: '',
-setActive,
+selectSession,
  signIn,
  signUp,
  };
@@ -108,7 +108,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  };

packages/expo/src/hooks/useSSO.ts

@@ -2,7 +2,7 @@ import { useSignIn, useSignUp } from '@clerk/react/legacy';
 import type {
  EnterpriseSSOStrategy,
  OAuthStrategy,
-SetActive,
+SelectSessionHook,
  SignInResource,
  SignUpResource,
 } from '@clerk/shared/types';
@@ -28,13 +28,13 @@ export type StartSSOFlowParams = {
 export type StartSSOFlowReturnType = {
  createdSessionId: string | null;
  authSessionResult: WebBrowser.WebBrowserAuthSessionResult | null;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
 };
 
 export function useSSO() {
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startSSOFlow(startSSOFlowParams: StartSSOFlowParams): Promise<StartSSOFlowReturnType> {
@@ -44,7 +44,7 @@ export function useSSO() {
  authSessionResult: null,
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -81,7 +81,7 @@ export function useSSO() {
  if (authSessionResult.type !== 'success' || !authSessionResult.url) {
  return {
  createdSessionId: null,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,
@@ -102,7 +102,7 @@ export function useSSO() {
 
  return {
  createdSessionId: signUp.createdSessionId ?? signIn.createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,

.changeset/split-setactive-into-select-methods.md

@@ -0,0 +1,92 @@
+---
+'@clerk/clerk-js': major
+'@clerk/shared': major
+'@clerk/react': major
+'@clerk/nextjs': major
+'@clerk/vue': major
+'@clerk/expo': major
+'@clerk/ui': major
+'@clerk/testing': major
+---
+
+Replace `setActive` with purpose-specific methods: `selectSession` and `selectOrganization`
+
+## Breaking Changes
+
+### `setActive` Removed from Public API
+
+The `setActive` method has been removed from the Clerk object and all hooks. Use the new purpose-specific methods instead:
+
+- `clerk.selectSession(session, options?)` - For session selection
+- `clerk.selectOrganization(organization, options?)` - For organization selection
+
+### Hook Return Types
+
+The following hooks no longer return `setActive`:
+
+- `useSignIn()` - now returns `selectSession` instead of `setActive`
+- `useSignUp()` - now returns `selectSession` instead of `setActive`
+- `useSessionList()` - now returns `selectSession` instead of `setActive`
+- `useOrganizationList()` - now returns `selectOrganization` instead of `setActive`
+
+### Migration
+
+**Before:**
+```tsx
+const { setActive } = useSignIn();
+await setActive({ session: createdSessionId });
+
+const { setActive } = useOrganizationList();
+await setActive({ organization: org });
+```
+
+**After:**
+```tsx
+const { selectSession } = useSignIn();
+await selectSession(createdSessionId);
+
+const { selectOrganization } = useOrganizationList();
+await selectOrganization(org);
+```
+
+### New Methods on Clerk Object
+
+Two new methods are available on the Clerk object:
+
+- `clerk.selectSession(session, options?)` - For session selection (sign-in, sign-up, multi-session switching)
+- `clerk.selectOrganization(organization, options?)` - For organization selection (org switching, personal workspace)
+
+### Options
+
+Both methods accept an options object:
+
+```tsx
+// selectSession options
+await selectSession(session, {
+ redirectUrl?: string;
+ navigate?: ({ session }) => void | Promise<void>;
+});
+
+// selectOrganization options
+await selectOrganization(organization, {
+ redirectUrl?: string;
+ navigate?: ({ session, organization }) => void | Promise<void>;
+});
+```
+
+### Expo Hooks
+
+The `StartGoogleAuthenticationFlowReturnType` and `StartAppleAuthenticationFlowReturnType` types now return `selectSession` instead of `setActive`.
+
+### Internal Window Hooks (Next.js)
+
+The internal window hooks have been renamed:
+- `__internal_onBeforeSetActive` → `__internal_onBeforeSelectSession`
+- `__internal_onAfterSetActive` → `__internal_onAfterSelectSession`
+
+### Types Removed
+
+The following types have been removed from the public API:
+- `SetActive`
+- `SetActiveParams`
+- `SetActiveNavigate` (use `SelectSessionNavigate` instead)

packages/clerk-js/src/core/clerk.ts

@@ -97,6 +97,8 @@ import type {
  RedirectOptions,
  Resources,
  SDKMetadata,
+ SelectOrganizationOptions,
+ SelectSessionOptions,
  SessionResource,
  SetActiveParams,
  SignedInSessionResource,
@@ -297,7 +299,7 @@ export class Clerk implements ClerkInterface {
  public __internal_isWebAuthnAutofillSupported: (() => Promise<boolean>) | undefined;
  public __internal_isWebAuthnPlatformAuthenticatorSupported: (() => Promise<boolean>) | undefined;
 
- public __internal_setActiveInProgress = false;
+ public __internal_selectSessionInProgress = false;
 
  get publishableKey(): string {
  return this.#publishableKey;
@@ -583,13 +585,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  const opts = callbackOrOptions && typeof callbackOrOptions === 'object' ? callbackOrOptions : options || {};
@@ -1446,7 +1448,7 @@ export class Clerk implements ClerkInterface {
  public setActive = async (params: SetActiveParams): Promise<void> => {
  const { organization, redirectUrl, navigate: setActiveNavigate } = params;
  let { session } = params;
- this.__internal_setActiveInProgress = true;
+ this.__internal_selectSessionInProgress = true;
  debugLogger.debug(
  'setActive() start',
  {
@@ -1476,13 +1478,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  let newSession = session === undefined ? this.session : session;
@@ -1605,10 +1607,79 @@ export class Clerk implements ClerkInterface {
  await onAfterSetActive();
  }
  } finally {
- this.__internal_setActiveInProgress = false;
+ this.__internal_selectSessionInProgress = false;
  }
  };
 
+ /**
+ * Select a session to make active.
+ *
+ * Use this method after sign-in or sign-up to activate the created session,
+ * or to switch between sessions in a multi-session application.
+ *
+ * Pass `null` to sign out and clear the active session.
+ */
+ public selectSession = async (
+ session: SignedInSessionResource | string | null,
+ options?: SelectSessionOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session: s }: { session: SessionResource }) => {
+ const result = await navigate({ session: s });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ session,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
+ /**
+ * Select an organization to make active within the current session.
+ *
+ * Use this method to switch between organizations or to select a personal workspace.
+ *
+ * Pass `null` to switch to the personal workspace (no active organization).
+ */
+ public selectOrganization = async (
+ organization: OrganizationResource | string | null,
+ options?: SelectOrganizationOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session }: { session: SessionResource }) => {
+ // Resolve the organization for the callback
+ const org =
+ organization === null
+ ? null
+ : typeof organization === 'string'
+ ? (this.organization ?? null)
+ : organization;
+
+ const result = await navigate({ session, organization: org });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ organization,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
  public addListener = (listener: ListenerCallback): UnsubscribeCallback => {
  listener = memoizeListenerCallback(listener);
  this.#listeners.push(listener);
@@ -2596,8 +2667,8 @@ export class Clerk implements ClerkInterface {
  const hasTransitionedToPendingStatus = this.session.status === 'active' && session?.status === 'pending';
  if (hasTransitionedToPendingStatus) {
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  // Execute hooks to update server authentication context and trigger

packages/clerk-js/src/core/resources/BillingCheckout.ts

@@ -204,7 +204,7 @@ export class CheckoutFlow implements CheckoutFlowResourceNonStrict {
  throw new Error('Clerk: `confirm()` must be called before `finalize()`');
  }
 
- await BillingCheckout.clerk.setActive({ session: BillingCheckout.clerk.session?.id, navigate });
+ await BillingCheckout.clerk.selectSession(BillingCheckout.clerk.session?.id ?? null, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignIn.ts

@@ -1243,7 +1243,7 @@ class SignInFuture implements SignInFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignIn.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -972,7 +972,7 @@ class SignUpFuture implements SignUpFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignUp.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 }

packages/clerk-js/src/global.d.ts

@@ -15,8 +15,8 @@ const __BUILD_VARIANT_CHANNEL__: boolean;
 const __BUILD_VARIANT_CHIPS__: boolean;
 
 interface Window {
-__internal_onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
-__internal_onAfterSetActive: () => Promise<void> | void;
+__internal_onBeforeSelectSession: (intent?: 'sign-out') => Promise<void> | void;
+__internal_onAfterSelectSession: () => Promise<void> | void;
  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
  __internal_ClerkUiCtor?: import('@clerk/shared/types').ClerkUiConstructor;
  /**

packages/clerk-js/src/test/mock-helpers.ts

@@ -99,7 +99,8 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  });
 
  mockProp(clerkAny, 'navigate');
- mockProp(clerkAny, 'setActive');
+ mockProp(clerkAny, 'selectSession');
+ mockProp(clerkAny, 'selectOrganization');
  mockProp(clerkAny, 'redirectWithAuth');
  mockProp(clerkAny, '__internal_navigateWithError');
  return clerkAny as DeepVitestMocked<LoadedClerk>;

packages/expo/src/hooks/useOAuth.ts

@@ -1,5 +1,5 @@
 import { useSignIn, useSignUp } from '@clerk/react/legacy';
-import type { OAuthStrategy, SetActive, SignInResource, SignUpResource } from '@clerk/shared/types';
+import type { OAuthStrategy, SelectSessionHook, SignInResource, SignUpResource } from '@clerk/shared/types';
 import * as AuthSession from 'expo-auth-session';
 import * as WebBrowser from 'expo-web-browser';
 
@@ -18,7 +18,7 @@ export type StartOAuthFlowParams = {
 
 export type StartOAuthFlowReturnType = {
  createdSessionId: string;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
  authSessionResult?: WebBrowser.WebBrowserAuthSessionResult;
@@ -33,7 +33,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return errorThrower.throw('Missing oauth strategy');
  }
 
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startOAuthFlow(startOAuthFlowParams?: StartOAuthFlowParams): Promise<StartOAuthFlowReturnType> {
@@ -42,7 +42,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  createdSessionId: '',
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -79,7 +79,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId: '',
-setActive,
+selectSession,
  signIn,
  signUp,
  };
@@ -108,7 +108,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  };

packages/expo/src/hooks/useSSO.ts

@@ -2,7 +2,7 @@ import { useSignIn, useSignUp } from '@clerk/react/legacy';
 import type {
  EnterpriseSSOStrategy,
  OAuthStrategy,
-SetActive,
+SelectSessionHook,
  SignInResource,
  SignUpResource,
 } from '@clerk/shared/types';
@@ -28,13 +28,13 @@ export type StartSSOFlowParams = {
 export type StartSSOFlowReturnType = {
  createdSessionId: string | null;
  authSessionResult: WebBrowser.WebBrowserAuthSessionResult | null;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
 };
 
 export function useSSO() {
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startSSOFlow(startSSOFlowParams: StartSSOFlowParams): Promise<StartSSOFlowReturnType> {
@@ -44,7 +44,7 @@ export function useSSO() {
  authSessionResult: null,
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -81,7 +81,7 @@ export function useSSO() {
  if (authSessionResult.type !== 'success' || !authSessionResult.url) {
  return {
  createdSessionId: null,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,
@@ -102,7 +102,7 @@ export function useSSO() {
 
  return {
  createdSessionId: signUp.createdSessionId ?? signIn.createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,

.changeset/split-setactive-into-select-methods.md

@@ -0,0 +1,92 @@
+---
+'@clerk/clerk-js': major
+'@clerk/shared': major
+'@clerk/react': major
+'@clerk/nextjs': major
+'@clerk/vue': major
+'@clerk/expo': major
+'@clerk/ui': major
+'@clerk/testing': major
+---
+
+Replace `setActive` with purpose-specific methods: `selectSession` and `selectOrganization`
+
+## Breaking Changes
+
+### `setActive` Removed from Public API
+
+The `setActive` method has been removed from the Clerk object and all hooks. Use the new purpose-specific methods instead:
+
+- `clerk.selectSession(session, options?)` - For session selection
+- `clerk.selectOrganization(organization, options?)` - For organization selection
+
+### Hook Return Types
+
+The following hooks no longer return `setActive`:
+
+- `useSignIn()` - now returns `selectSession` instead of `setActive`
+- `useSignUp()` - now returns `selectSession` instead of `setActive`
+- `useSessionList()` - now returns `selectSession` instead of `setActive`
+- `useOrganizationList()` - now returns `selectOrganization` instead of `setActive`
+
+### Migration
+
+**Before:**
+```tsx
+const { setActive } = useSignIn();
+await setActive({ session: createdSessionId });
+
+const { setActive } = useOrganizationList();
+await setActive({ organization: org });
+```
+
+**After:**
+```tsx
+const { selectSession } = useSignIn();
+await selectSession(createdSessionId);
+
+const { selectOrganization } = useOrganizationList();
+await selectOrganization(org);
+```
+
+### New Methods on Clerk Object
+
+Two new methods are available on the Clerk object:
+
+- `clerk.selectSession(session, options?)` - For session selection (sign-in, sign-up, multi-session switching)
+- `clerk.selectOrganization(organization, options?)` - For organization selection (org switching, personal workspace)
+
+### Options
+
+Both methods accept an options object:
+
+```tsx
+// selectSession options
+await selectSession(session, {
+ redirectUrl?: string;
+ navigate?: ({ session }) => void | Promise<void>;
+});
+
+// selectOrganization options
+await selectOrganization(organization, {
+ redirectUrl?: string;
+ navigate?: ({ session, organization }) => void | Promise<void>;
+});
+```
+
+### Expo Hooks
+
+The `StartGoogleAuthenticationFlowReturnType` and `StartAppleAuthenticationFlowReturnType` types now return `selectSession` instead of `setActive`.
+
+### Internal Window Hooks (Next.js)
+
+The internal window hooks have been renamed:
+- `__internal_onBeforeSetActive` → `__internal_onBeforeSelectSession`
+- `__internal_onAfterSetActive` → `__internal_onAfterSelectSession`
+
+### Types Removed
+
+The following types have been removed from the public API:
+- `SetActive`
+- `SetActiveParams`
+- `SetActiveNavigate` (use `SelectSessionNavigate` instead)

packages/clerk-js/src/core/clerk.ts

@@ -97,6 +97,8 @@ import type {
  RedirectOptions,
  Resources,
  SDKMetadata,
+ SelectOrganizationOptions,
+ SelectSessionOptions,
  SessionResource,
  SetActiveParams,
  SignedInSessionResource,
@@ -297,7 +299,7 @@ export class Clerk implements ClerkInterface {
  public __internal_isWebAuthnAutofillSupported: (() => Promise<boolean>) | undefined;
  public __internal_isWebAuthnPlatformAuthenticatorSupported: (() => Promise<boolean>) | undefined;
 
- public __internal_setActiveInProgress = false;
+ public __internal_selectSessionInProgress = false;
 
  get publishableKey(): string {
  return this.#publishableKey;
@@ -583,13 +585,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  const opts = callbackOrOptions && typeof callbackOrOptions === 'object' ? callbackOrOptions : options || {};
@@ -1446,7 +1448,7 @@ export class Clerk implements ClerkInterface {
  public setActive = async (params: SetActiveParams): Promise<void> => {
  const { organization, redirectUrl, navigate: setActiveNavigate } = params;
  let { session } = params;
- this.__internal_setActiveInProgress = true;
+ this.__internal_selectSessionInProgress = true;
  debugLogger.debug(
  'setActive() start',
  {
@@ -1476,13 +1478,13 @@ export class Clerk implements ClerkInterface {
  }
 
  const onBeforeSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
- ? window.__internal_onBeforeSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+ ? window.__internal_onBeforeSelectSession
  : noop;
 
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  let newSession = session === undefined ? this.session : session;
@@ -1605,10 +1607,79 @@ export class Clerk implements ClerkInterface {
  await onAfterSetActive();
  }
  } finally {
- this.__internal_setActiveInProgress = false;
+ this.__internal_selectSessionInProgress = false;
  }
  };
 
+ /**
+ * Select a session to make active.
+ *
+ * Use this method after sign-in or sign-up to activate the created session,
+ * or to switch between sessions in a multi-session application.
+ *
+ * Pass `null` to sign out and clear the active session.
+ */
+ public selectSession = async (
+ session: SignedInSessionResource | string | null,
+ options?: SelectSessionOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session: s }: { session: SessionResource }) => {
+ const result = await navigate({ session: s });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ session,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
+ /**
+ * Select an organization to make active within the current session.
+ *
+ * Use this method to switch between organizations or to select a personal workspace.
+ *
+ * Pass `null` to switch to the personal workspace (no active organization).
+ */
+ public selectOrganization = async (
+ organization: OrganizationResource | string | null,
+ options?: SelectOrganizationOptions,
+ ): Promise<void> => {
+ const { navigate, redirectUrl } = options ?? {};
+
+ // Convert navigate callback to setActive format if provided
+ const setActiveNavigate = navigate
+ ? async ({ session }: { session: SessionResource }) => {
+ // Resolve the organization for the callback
+ const org =
+ organization === null
+ ? null
+ : typeof organization === 'string'
+ ? (this.organization ?? null)
+ : organization;
+
+ const result = await navigate({ session, organization: org });
+ if (typeof result === 'string') {
+ await this.navigate(result);
+ }
+ }
+ : undefined;
+
+ return this.setActive({
+ organization,
+ navigate: setActiveNavigate,
+ redirectUrl,
+ });
+ };
+
  public addListener = (listener: ListenerCallback): UnsubscribeCallback => {
  listener = memoizeListenerCallback(listener);
  this.#listeners.push(listener);
@@ -2596,8 +2667,8 @@ export class Clerk implements ClerkInterface {
  const hasTransitionedToPendingStatus = this.session.status === 'active' && session?.status === 'pending';
  if (hasTransitionedToPendingStatus) {
  const onAfterSetActive: SetActiveHook =
- typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
- ? window.__internal_onAfterSetActive
+ typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+ ? window.__internal_onAfterSelectSession
  : noop;
 
  // Execute hooks to update server authentication context and trigger

packages/clerk-js/src/core/resources/BillingCheckout.ts

@@ -204,7 +204,7 @@ export class CheckoutFlow implements CheckoutFlowResourceNonStrict {
  throw new Error('Clerk: `confirm()` must be called before `finalize()`');
  }
 
- await BillingCheckout.clerk.setActive({ session: BillingCheckout.clerk.session?.id, navigate });
+ await BillingCheckout.clerk.selectSession(BillingCheckout.clerk.session?.id ?? null, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignIn.ts

@@ -1243,7 +1243,7 @@ class SignInFuture implements SignInFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignIn.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -972,7 +972,7 @@ class SignUpFuture implements SignUpFutureResource {
  }
 
  this.#hasBeenFinalized = true;
- await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+ await SignUp.clerk.selectSession(this.#resource.createdSessionId, { navigate });
  });
  }
 }

packages/clerk-js/src/global.d.ts

@@ -15,8 +15,8 @@ const __BUILD_VARIANT_CHANNEL__: boolean;
 const __BUILD_VARIANT_CHIPS__: boolean;
 
 interface Window {
-__internal_onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
-__internal_onAfterSetActive: () => Promise<void> | void;
+__internal_onBeforeSelectSession: (intent?: 'sign-out') => Promise<void> | void;
+__internal_onAfterSelectSession: () => Promise<void> | void;
  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
  __internal_ClerkUiCtor?: import('@clerk/shared/types').ClerkUiConstructor;
  /**

packages/clerk-js/src/test/mock-helpers.ts

@@ -99,7 +99,8 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  });
 
  mockProp(clerkAny, 'navigate');
- mockProp(clerkAny, 'setActive');
+ mockProp(clerkAny, 'selectSession');
+ mockProp(clerkAny, 'selectOrganization');
  mockProp(clerkAny, 'redirectWithAuth');
  mockProp(clerkAny, '__internal_navigateWithError');
  return clerkAny as DeepVitestMocked<LoadedClerk>;

packages/expo/src/hooks/useOAuth.ts

@@ -1,5 +1,5 @@
 import { useSignIn, useSignUp } from '@clerk/react/legacy';
-import type { OAuthStrategy, SetActive, SignInResource, SignUpResource } from '@clerk/shared/types';
+import type { OAuthStrategy, SelectSessionHook, SignInResource, SignUpResource } from '@clerk/shared/types';
 import * as AuthSession from 'expo-auth-session';
 import * as WebBrowser from 'expo-web-browser';
 
@@ -18,7 +18,7 @@ export type StartOAuthFlowParams = {
 
 export type StartOAuthFlowReturnType = {
  createdSessionId: string;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
  authSessionResult?: WebBrowser.WebBrowserAuthSessionResult;
@@ -33,7 +33,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return errorThrower.throw('Missing oauth strategy');
  }
 
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startOAuthFlow(startOAuthFlowParams?: StartOAuthFlowParams): Promise<StartOAuthFlowReturnType> {
@@ -42,7 +42,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  createdSessionId: '',
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -79,7 +79,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId: '',
-setActive,
+selectSession,
  signIn,
  signUp,
  };
@@ -108,7 +108,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
  return {
  authSessionResult,
  createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  };

packages/expo/src/hooks/useSSO.ts

@@ -2,7 +2,7 @@ import { useSignIn, useSignUp } from '@clerk/react/legacy';
 import type {
  EnterpriseSSOStrategy,
  OAuthStrategy,
-SetActive,
+SelectSessionHook,
  SignInResource,
  SignUpResource,
 } from '@clerk/shared/types';
@@ -28,13 +28,13 @@ export type StartSSOFlowParams = {
 export type StartSSOFlowReturnType = {
  createdSessionId: string | null;
  authSessionResult: WebBrowser.WebBrowserAuthSessionResult | null;
-setActive?: SetActive;
+selectSession?: SelectSessionHook;
  signIn?: SignInResource;
  signUp?: SignUpResource;
 };
 
 export function useSSO() {
- const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+ const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
  async function startSSOFlow(startSSOFlowParams: StartSSOFlowParams): Promise<StartSSOFlowReturnType> {
@@ -44,7 +44,7 @@ export function useSSO() {
  authSessionResult: null,
  signIn,
  signUp,
-setActive,
+selectSession,
  };
  }
 
@@ -81,7 +81,7 @@ export function useSSO() {
  if (authSessionResult.type !== 'success' || !authSessionResult.url) {
  return {
  createdSessionId: null,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,
@@ -102,7 +102,7 @@ export function useSSO() {
 
  return {
  createdSessionId: signUp.createdSessionId ?? signIn.createdSessionId,
-setActive,
+selectSession,
  signIn,
  signUp,
  authSessionResult,