fix(shared): Correct useOrganizationList/useOrganization loading state

.changeset/fix-useorganizationlist-empty-render.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix `useOrganizationList` and `useOrganization` briefly reporting paginated resources as `isLoading: false` with empty data before the query starts.

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -0,0 +1,130 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { useClerkInfiniteQuery } from '../useInfiniteQuery';
+import { useClerkQuery } from '../useQuery';
+
+let activeClerk: any;
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => activeClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
+
+const makeClerkWithoutQueryClient = () => {
+ const mockClerk = createMockClerk({ queryClient: null });
+ Object.defineProperty(mockClerk, '__internal_queryClient', {
+ get: () => undefined,
+ configurable: true,
+ });
+ return mockClerk;
+};
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+describe('useBaseQuery - dummy result while query client is not attached', () => {
+ beforeEach(() => {
+ activeClerk = makeClerkWithoutQueryClient();
+ });
+
+ it('reports isLoading: true when the query would be enabled', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-enabled'],
+ queryFn,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('reports isLoading: false when enabled is explicitly false', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-disabled'],
+ queryFn,
+ enabled: false,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(false);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('defaults to enabled when the option is omitted', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-default'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ });
+
+ it('applies the same invariant to useClerkInfiniteQuery', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkInfiniteQuery({
+ queryKey: ['useBaseQuery-pre-client-infinite'],
+ queryFn,
+ initialPageParam: 1,
+ getNextPageParam: () => undefined,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+});
+
+describe('useBaseQuery - normal behavior once query client attaches', () => {
+ it('delegates to the real observer when the query client is loaded', async () => {
+ const queryClient = createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient });
+
+ const queryFn = vi.fn(async () => 'result');
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-loaded-client'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toBe('result');
+ expect(queryFn).toHaveBeenCalledTimes(1);
+ });
+});

packages/shared/src/react/clerk-rq/useBaseQuery.ts

@@ -62,13 +62,16 @@ export function useBaseQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey
  }, [defaultedOptions, observer]);
 
  if (!isQueryClientLoaded) {
- // In this step we attempt to return a dummy result that matches RQ's pending state while on SSR or until the query client is loaded on the client (after clerk-js loads).
- // When the query client is not loaded, we return the result as if the query was not enabled.
- // `isLoading` and `isFetching` need to be `false` because we can't know if the query will be enabled during SSR since most conditions rely on client-only data that are available after clerk-js loads.
+ // Return a dummy result that matches RQ's pending state until the query client loads
+ // (SSR, or on the client before clerk-js finishes bootstrapping it).
+ // `isLoading` reflects whether the query *would* run once the client attaches — otherwise
+ // consumers see `isLoading: false` with empty data and render a spurious "no results" state
+ // in the window between clerk.loaded and the query client being ready.
+ const isEnabled = options.enabled !== false;
  return {
  data: undefined,
  error: null,
- isLoading: false,
+ isLoading: isEnabled,
  isFetching: false,
  status: 'pending',
  };

.changeset/fix-useorganizationlist-empty-render.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix `useOrganizationList` and `useOrganization` briefly reporting paginated resources as `isLoading: false` with empty data before the query starts.

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -0,0 +1,130 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { useClerkInfiniteQuery } from '../useInfiniteQuery';
+import { useClerkQuery } from '../useQuery';
+
+let activeClerk: any;
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => activeClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
+
+const makeClerkWithoutQueryClient = () => {
+ const mockClerk = createMockClerk({ queryClient: null });
+ Object.defineProperty(mockClerk, '__internal_queryClient', {
+ get: () => undefined,
+ configurable: true,
+ });
+ return mockClerk;
+};
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+describe('useBaseQuery - dummy result while query client is not attached', () => {
+ beforeEach(() => {
+ activeClerk = makeClerkWithoutQueryClient();
+ });
+
+ it('reports isLoading: true when the query would be enabled', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-enabled'],
+ queryFn,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('reports isLoading: false when enabled is explicitly false', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-disabled'],
+ queryFn,
+ enabled: false,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(false);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('defaults to enabled when the option is omitted', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-default'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ });
+
+ it('applies the same invariant to useClerkInfiniteQuery', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkInfiniteQuery({
+ queryKey: ['useBaseQuery-pre-client-infinite'],
+ queryFn,
+ initialPageParam: 1,
+ getNextPageParam: () => undefined,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+});
+
+describe('useBaseQuery - normal behavior once query client attaches', () => {
+ it('delegates to the real observer when the query client is loaded', async () => {
+ const queryClient = createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient });
+
+ const queryFn = vi.fn(async () => 'result');
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-loaded-client'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toBe('result');
+ expect(queryFn).toHaveBeenCalledTimes(1);
+ });
+});

packages/shared/src/react/clerk-rq/useBaseQuery.ts

@@ -62,13 +62,16 @@ export function useBaseQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey
  }, [defaultedOptions, observer]);
 
  if (!isQueryClientLoaded) {
- // In this step we attempt to return a dummy result that matches RQ's pending state while on SSR or until the query client is loaded on the client (after clerk-js loads).
- // When the query client is not loaded, we return the result as if the query was not enabled.
- // `isLoading` and `isFetching` need to be `false` because we can't know if the query will be enabled during SSR since most conditions rely on client-only data that are available after clerk-js loads.
+ // Return a dummy result that matches RQ's pending state until the query client loads
+ // (SSR, or on the client before clerk-js finishes bootstrapping it).
+ // `isLoading` reflects whether the query *would* run once the client attaches — otherwise
+ // consumers see `isLoading: false` with empty data and render a spurious "no results" state
+ // in the window between clerk.loaded and the query client being ready.
+ const isEnabled = options.enabled !== false;
  return {
  data: undefined,
  error: null,
- isLoading: false,
+ isLoading: isEnabled,
  isFetching: false,
  status: 'pending',
  };

.changeset/fix-useorganizationlist-empty-render.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix `useOrganizationList` and `useOrganization` briefly reporting paginated resources as `isLoading: false` with empty data before the query starts.

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -0,0 +1,130 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { useClerkInfiniteQuery } from '../useInfiniteQuery';
+import { useClerkQuery } from '../useQuery';
+
+let activeClerk: any;
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => activeClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
+
+const makeClerkWithoutQueryClient = () => {
+ const mockClerk = createMockClerk({ queryClient: null });
+ Object.defineProperty(mockClerk, '__internal_queryClient', {
+ get: () => undefined,
+ configurable: true,
+ });
+ return mockClerk;
+};
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+describe('useBaseQuery - dummy result while query client is not attached', () => {
+ beforeEach(() => {
+ activeClerk = makeClerkWithoutQueryClient();
+ });
+
+ it('reports isLoading: true when the query would be enabled', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-enabled'],
+ queryFn,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('reports isLoading: false when enabled is explicitly false', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-disabled'],
+ queryFn,
+ enabled: false,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(false);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('defaults to enabled when the option is omitted', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-default'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ });
+
+ it('applies the same invariant to useClerkInfiniteQuery', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkInfiniteQuery({
+ queryKey: ['useBaseQuery-pre-client-infinite'],
+ queryFn,
+ initialPageParam: 1,
+ getNextPageParam: () => undefined,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+});
+
+describe('useBaseQuery - normal behavior once query client attaches', () => {
+ it('delegates to the real observer when the query client is loaded', async () => {
+ const queryClient = createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient });
+
+ const queryFn = vi.fn(async () => 'result');
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-loaded-client'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toBe('result');
+ expect(queryFn).toHaveBeenCalledTimes(1);
+ });
+});

packages/shared/src/react/clerk-rq/useBaseQuery.ts

@@ -62,13 +62,16 @@ export function useBaseQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey
  }, [defaultedOptions, observer]);
 
  if (!isQueryClientLoaded) {
- // In this step we attempt to return a dummy result that matches RQ's pending state while on SSR or until the query client is loaded on the client (after clerk-js loads).
- // When the query client is not loaded, we return the result as if the query was not enabled.
- // `isLoading` and `isFetching` need to be `false` because we can't know if the query will be enabled during SSR since most conditions rely on client-only data that are available after clerk-js loads.
+ // Return a dummy result that matches RQ's pending state until the query client loads
+ // (SSR, or on the client before clerk-js finishes bootstrapping it).
+ // `isLoading` reflects whether the query *would* run once the client attaches — otherwise
+ // consumers see `isLoading: false` with empty data and render a spurious "no results" state
+ // in the window between clerk.loaded and the query client being ready.
+ const isEnabled = options.enabled !== false;
  return {
  data: undefined,
  error: null,
- isLoading: false,
+ isLoading: isEnabled,
  isFetching: false,
  status: 'pending',
  };

.changeset/fix-useorganizationlist-empty-render.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix `useOrganizationList` and `useOrganization` briefly reporting paginated resources as `isLoading: false` with empty data before the query starts.

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -0,0 +1,130 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { useClerkInfiniteQuery } from '../useInfiniteQuery';
+import { useClerkQuery } from '../useQuery';
+
+let activeClerk: any;
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => activeClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
+
+const makeClerkWithoutQueryClient = () => {
+ const mockClerk = createMockClerk({ queryClient: null });
+ Object.defineProperty(mockClerk, '__internal_queryClient', {
+ get: () => undefined,
+ configurable: true,
+ });
+ return mockClerk;
+};
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+describe('useBaseQuery - dummy result while query client is not attached', () => {
+ beforeEach(() => {
+ activeClerk = makeClerkWithoutQueryClient();
+ });
+
+ it('reports isLoading: true when the query would be enabled', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-enabled'],
+ queryFn,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('reports isLoading: false when enabled is explicitly false', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-disabled'],
+ queryFn,
+ enabled: false,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(false);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('defaults to enabled when the option is omitted', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-default'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ });
+
+ it('applies the same invariant to useClerkInfiniteQuery', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkInfiniteQuery({
+ queryKey: ['useBaseQuery-pre-client-infinite'],
+ queryFn,
+ initialPageParam: 1,
+ getNextPageParam: () => undefined,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+});
+
+describe('useBaseQuery - normal behavior once query client attaches', () => {
+ it('delegates to the real observer when the query client is loaded', async () => {
+ const queryClient = createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient });
+
+ const queryFn = vi.fn(async () => 'result');
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-loaded-client'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toBe('result');
+ expect(queryFn).toHaveBeenCalledTimes(1);
+ });
+});

packages/shared/src/react/clerk-rq/useBaseQuery.ts

@@ -62,13 +62,16 @@ export function useBaseQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey
  }, [defaultedOptions, observer]);
 
  if (!isQueryClientLoaded) {
- // In this step we attempt to return a dummy result that matches RQ's pending state while on SSR or until the query client is loaded on the client (after clerk-js loads).
- // When the query client is not loaded, we return the result as if the query was not enabled.
- // `isLoading` and `isFetching` need to be `false` because we can't know if the query will be enabled during SSR since most conditions rely on client-only data that are available after clerk-js loads.
+ // Return a dummy result that matches RQ's pending state until the query client loads
+ // (SSR, or on the client before clerk-js finishes bootstrapping it).
+ // `isLoading` reflects whether the query *would* run once the client attaches — otherwise
+ // consumers see `isLoading: false` with empty data and render a spurious "no results" state
+ // in the window between clerk.loaded and the query client being ready.
+ const isEnabled = options.enabled !== false;
  return {
  data: undefined,
  error: null,
- isLoading: false,
+ isLoading: isEnabled,
  isFetching: false,
  status: 'pending',
  };

.changeset/fix-useorganizationlist-empty-render.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix `useOrganizationList` and `useOrganization` briefly reporting paginated resources as `isLoading: false` with empty data before the query starts.

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -0,0 +1,130 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { useClerkInfiniteQuery } from '../useInfiniteQuery';
+import { useClerkQuery } from '../useQuery';
+
+let activeClerk: any;
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => activeClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
+
+const makeClerkWithoutQueryClient = () => {
+ const mockClerk = createMockClerk({ queryClient: null });
+ Object.defineProperty(mockClerk, '__internal_queryClient', {
+ get: () => undefined,
+ configurable: true,
+ });
+ return mockClerk;
+};
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+describe('useBaseQuery - dummy result while query client is not attached', () => {
+ beforeEach(() => {
+ activeClerk = makeClerkWithoutQueryClient();
+ });
+
+ it('reports isLoading: true when the query would be enabled', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-enabled'],
+ queryFn,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('reports isLoading: false when enabled is explicitly false', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-disabled'],
+ queryFn,
+ enabled: false,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(false);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('defaults to enabled when the option is omitted', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-default'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ });
+
+ it('applies the same invariant to useClerkInfiniteQuery', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkInfiniteQuery({
+ queryKey: ['useBaseQuery-pre-client-infinite'],
+ queryFn,
+ initialPageParam: 1,
+ getNextPageParam: () => undefined,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+});
+
+describe('useBaseQuery - normal behavior once query client attaches', () => {
+ it('delegates to the real observer when the query client is loaded', async () => {
+ const queryClient = createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient });
+
+ const queryFn = vi.fn(async () => 'result');
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-loaded-client'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toBe('result');
+ expect(queryFn).toHaveBeenCalledTimes(1);
+ });
+});

packages/shared/src/react/clerk-rq/useBaseQuery.ts

@@ -62,13 +62,16 @@ export function useBaseQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey
  }, [defaultedOptions, observer]);
 
  if (!isQueryClientLoaded) {
- // In this step we attempt to return a dummy result that matches RQ's pending state while on SSR or until the query client is loaded on the client (after clerk-js loads).
- // When the query client is not loaded, we return the result as if the query was not enabled.
- // `isLoading` and `isFetching` need to be `false` because we can't know if the query will be enabled during SSR since most conditions rely on client-only data that are available after clerk-js loads.
+ // Return a dummy result that matches RQ's pending state until the query client loads
+ // (SSR, or on the client before clerk-js finishes bootstrapping it).
+ // `isLoading` reflects whether the query *would* run once the client attaches — otherwise
+ // consumers see `isLoading: false` with empty data and render a spurious "no results" state
+ // in the window between clerk.loaded and the query client being ready.
+ const isEnabled = options.enabled !== false;
  return {
  data: undefined,
  error: null,
- isLoading: false,
+ isLoading: isEnabled,
  isFetching: false,
  status: 'pending',
  };

.changeset/fix-useorganizationlist-empty-render.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix `useOrganizationList` and `useOrganization` briefly reporting paginated resources as `isLoading: false` with empty data before the query starts.

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -0,0 +1,130 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { useClerkInfiniteQuery } from '../useInfiniteQuery';
+import { useClerkQuery } from '../useQuery';
+
+let activeClerk: any;
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => activeClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
+
+const makeClerkWithoutQueryClient = () => {
+ const mockClerk = createMockClerk({ queryClient: null });
+ Object.defineProperty(mockClerk, '__internal_queryClient', {
+ get: () => undefined,
+ configurable: true,
+ });
+ return mockClerk;
+};
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+describe('useBaseQuery - dummy result while query client is not attached', () => {
+ beforeEach(() => {
+ activeClerk = makeClerkWithoutQueryClient();
+ });
+
+ it('reports isLoading: true when the query would be enabled', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-enabled'],
+ queryFn,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('reports isLoading: false when enabled is explicitly false', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-disabled'],
+ queryFn,
+ enabled: false,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(false);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('defaults to enabled when the option is omitted', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-default'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ });
+
+ it('applies the same invariant to useClerkInfiniteQuery', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkInfiniteQuery({
+ queryKey: ['useBaseQuery-pre-client-infinite'],
+ queryFn,
+ initialPageParam: 1,
+ getNextPageParam: () => undefined,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+});
+
+describe('useBaseQuery - normal behavior once query client attaches', () => {
+ it('delegates to the real observer when the query client is loaded', async () => {
+ const queryClient = createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient });
+
+ const queryFn = vi.fn(async () => 'result');
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-loaded-client'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toBe('result');
+ expect(queryFn).toHaveBeenCalledTimes(1);
+ });
+});

packages/shared/src/react/clerk-rq/useBaseQuery.ts

@@ -62,13 +62,16 @@ export function useBaseQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey
  }, [defaultedOptions, observer]);
 
  if (!isQueryClientLoaded) {
- // In this step we attempt to return a dummy result that matches RQ's pending state while on SSR or until the query client is loaded on the client (after clerk-js loads).
- // When the query client is not loaded, we return the result as if the query was not enabled.
- // `isLoading` and `isFetching` need to be `false` because we can't know if the query will be enabled during SSR since most conditions rely on client-only data that are available after clerk-js loads.
+ // Return a dummy result that matches RQ's pending state until the query client loads
+ // (SSR, or on the client before clerk-js finishes bootstrapping it).
+ // `isLoading` reflects whether the query *would* run once the client attaches — otherwise
+ // consumers see `isLoading: false` with empty data and render a spurious "no results" state
+ // in the window between clerk.loaded and the query client being ready.
+ const isEnabled = options.enabled !== false;
  return {
  data: undefined,
  error: null,
- isLoading: false,
+ isLoading: isEnabled,
  isFetching: false,
  status: 'pending',
  };

.changeset/fix-useorganizationlist-empty-render.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix `useOrganizationList` and `useOrganization` briefly reporting paginated resources as `isLoading: false` with empty data before the query starts.

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -0,0 +1,130 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { useClerkInfiniteQuery } from '../useInfiniteQuery';
+import { useClerkQuery } from '../useQuery';
+
+let activeClerk: any;
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => activeClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
+
+const makeClerkWithoutQueryClient = () => {
+ const mockClerk = createMockClerk({ queryClient: null });
+ Object.defineProperty(mockClerk, '__internal_queryClient', {
+ get: () => undefined,
+ configurable: true,
+ });
+ return mockClerk;
+};
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+describe('useBaseQuery - dummy result while query client is not attached', () => {
+ beforeEach(() => {
+ activeClerk = makeClerkWithoutQueryClient();
+ });
+
+ it('reports isLoading: true when the query would be enabled', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-enabled'],
+ queryFn,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('reports isLoading: false when enabled is explicitly false', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-disabled'],
+ queryFn,
+ enabled: false,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(false);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('defaults to enabled when the option is omitted', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-default'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ });
+
+ it('applies the same invariant to useClerkInfiniteQuery', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkInfiniteQuery({
+ queryKey: ['useBaseQuery-pre-client-infinite'],
+ queryFn,
+ initialPageParam: 1,
+ getNextPageParam: () => undefined,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+});
+
+describe('useBaseQuery - normal behavior once query client attaches', () => {
+ it('delegates to the real observer when the query client is loaded', async () => {
+ const queryClient = createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient });
+
+ const queryFn = vi.fn(async () => 'result');
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-loaded-client'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toBe('result');
+ expect(queryFn).toHaveBeenCalledTimes(1);
+ });
+});

packages/shared/src/react/clerk-rq/useBaseQuery.ts

@@ -62,13 +62,16 @@ export function useBaseQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey
  }, [defaultedOptions, observer]);
 
  if (!isQueryClientLoaded) {
- // In this step we attempt to return a dummy result that matches RQ's pending state while on SSR or until the query client is loaded on the client (after clerk-js loads).
- // When the query client is not loaded, we return the result as if the query was not enabled.
- // `isLoading` and `isFetching` need to be `false` because we can't know if the query will be enabled during SSR since most conditions rely on client-only data that are available after clerk-js loads.
+ // Return a dummy result that matches RQ's pending state until the query client loads
+ // (SSR, or on the client before clerk-js finishes bootstrapping it).
+ // `isLoading` reflects whether the query *would* run once the client attaches — otherwise
+ // consumers see `isLoading: false` with empty data and render a spurious "no results" state
+ // in the window between clerk.loaded and the query client being ready.
+ const isEnabled = options.enabled !== false;
  return {
  data: undefined,
  error: null,
- isLoading: false,
+ isLoading: isEnabled,
  isFetching: false,
  status: 'pending',
  };

.changeset/fix-useorganizationlist-empty-render.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix `useOrganizationList` and `useOrganization` briefly reporting paginated resources as `isLoading: false` with empty data before the query starts.

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -0,0 +1,130 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { useClerkInfiniteQuery } from '../useInfiniteQuery';
+import { useClerkQuery } from '../useQuery';
+
+let activeClerk: any;
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => activeClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
+
+const makeClerkWithoutQueryClient = () => {
+ const mockClerk = createMockClerk({ queryClient: null });
+ Object.defineProperty(mockClerk, '__internal_queryClient', {
+ get: () => undefined,
+ configurable: true,
+ });
+ return mockClerk;
+};
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+describe('useBaseQuery - dummy result while query client is not attached', () => {
+ beforeEach(() => {
+ activeClerk = makeClerkWithoutQueryClient();
+ });
+
+ it('reports isLoading: true when the query would be enabled', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-enabled'],
+ queryFn,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('reports isLoading: false when enabled is explicitly false', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-disabled'],
+ queryFn,
+ enabled: false,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(false);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.status).toBe('pending');
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+
+ it('defaults to enabled when the option is omitted', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-pre-client-default'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ });
+
+ it('applies the same invariant to useClerkInfiniteQuery', () => {
+ const queryFn = vi.fn();
+ const { result } = renderHook(
+ () =>
+ useClerkInfiniteQuery({
+ queryKey: ['useBaseQuery-pre-client-infinite'],
+ queryFn,
+ initialPageParam: 1,
+ getNextPageParam: () => undefined,
+ enabled: true,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.isFetching).toBe(false);
+ expect(result.current.data).toBeUndefined();
+ expect(queryFn).not.toHaveBeenCalled();
+ });
+});
+
+describe('useBaseQuery - normal behavior once query client attaches', () => {
+ it('delegates to the real observer when the query client is loaded', async () => {
+ const queryClient = createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient });
+
+ const queryFn = vi.fn(async () => 'result');
+ const { result } = renderHook(
+ () =>
+ useClerkQuery({
+ queryKey: ['useBaseQuery-loaded-client'],
+ queryFn,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current.isLoading).toBe(true);
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toBe('result');
+ expect(queryFn).toHaveBeenCalledTimes(1);
+ });
+});

packages/shared/src/react/clerk-rq/useBaseQuery.ts

@@ -62,13 +62,16 @@ export function useBaseQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey
  }, [defaultedOptions, observer]);
 
  if (!isQueryClientLoaded) {
- // In this step we attempt to return a dummy result that matches RQ's pending state while on SSR or until the query client is loaded on the client (after clerk-js loads).
- // When the query client is not loaded, we return the result as if the query was not enabled.
- // `isLoading` and `isFetching` need to be `false` because we can't know if the query will be enabled during SSR since most conditions rely on client-only data that are available after clerk-js loads.
+ // Return a dummy result that matches RQ's pending state until the query client loads
+ // (SSR, or on the client before clerk-js finishes bootstrapping it).
+ // `isLoading` reflects whether the query *would* run once the client attaches — otherwise
+ // consumers see `isLoading: false` with empty data and render a spurious "no results" state
+ // in the window between clerk.loaded and the query client being ready.
+ const isEnabled = options.enabled !== false;
  return {
  data: undefined,
  error: null,
- isLoading: false,
+ isLoading: isEnabled,
  isFetching: false,
  status: 'pending',
  };