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',
     };