From 39ebd9cff1c919b2a24cd6f0937c8cc706cf0ec6 Mon Sep 17 00:00:00 2001
From: Ian Macartney <ianhmacartney@gmail.com>
Date: Thu, 20 Nov 2025 19:24:03 -0800
Subject: [PATCH 1/2] try skip overload

---
 .../convex/src/browser/query_options.ts       |  2 +-
 npm-packages/convex/src/react/client.ts       | 38 +++++++++++--------
 .../convex/src/react/use_query.test.ts        |  6 +++
 3 files changed, 30 insertions(+), 16 deletions(-)

diff --git a/npm-packages/convex/src/browser/query_options.ts b/npm-packages/convex/src/browser/query_options.ts
index 7ac46041e..621910a97 100644
--- a/npm-packages/convex/src/browser/query_options.ts
+++ b/npm-packages/convex/src/browser/query_options.ts
@@ -22,6 +22,6 @@ export type QueryOptions<Query extends FunctionReference<"query">> = {
 // This helper helps more once we have more inference happening.
 export function convexQueryOptions<Query extends FunctionReference<"query">>(
   options: QueryOptions<Query>,
-) {
+): QueryOptions<Query> {
   return options;
 }
diff --git a/npm-packages/convex/src/react/client.ts b/npm-packages/convex/src/react/client.ts
index 12e8b2b83..65fde6e7b 100644
--- a/npm-packages/convex/src/react/client.ts
+++ b/npm-packages/convex/src/react/client.ts
@@ -808,20 +808,26 @@ export type OptionalRestArgsOrSkip<FuncRef extends FunctionReference<any>> =
  *
  * @public
  */
-export type UseQueryOptions<Query extends FunctionReference<"query">> =
-  QueryOptions<Query> & {
-    /**
-     * Whether to throw an error if the query fails.
-     * If false, the error will be returned in the `error` field.
-     * @defaultValue false
-     */
-    throwOnError?: boolean;
-    /**
-     * An initial value to use before the query result is available.
-     * @defaultValue undefined
-     */
-    initialValue?: Query["_returnType"];
-  };
+export type UseQueryOptions<Query extends FunctionReference<"query">> = (
+  | (QueryOptions<Query> & { skip?: false })
+  | {
+      query: Query;
+      args?: NoInfer<unknown>;
+      skip: true;
+    }
+) & {
+  /**
+   * Whether to throw an error if the query fails.
+   * If false, the error will be returned in the `error` field.
+   * @defaultValue false
+   */
+  throwOnError?: boolean;
+  /**
+   * An initial value to use before the query result is available.
+   * @defaultValue undefined
+   */
+  initialValue?: Query["_returnType"];
+};
 
 /**
  * Options for the object-based {@link useQuery} overload with a preloaded query.
@@ -941,7 +947,9 @@ export function useQuery<Query extends FunctionReference<"query">>(
         typeof query === "string"
           ? (makeFunctionReference<"query", any, any>(query) as Query)
           : query;
-      argsObject = queryOrOptions.args ?? ({} as Record<string, Value>);
+      if (!queryOrOptions.skip && queryOrOptions.args) {
+        argsObject = queryOrOptions.args;
+      }
       throwOnError = queryOrOptions.throwOnError ?? false;
       initialValue = queryOrOptions.initialValue;
     }
diff --git a/npm-packages/convex/src/react/use_query.test.ts b/npm-packages/convex/src/react/use_query.test.ts
index 503dee2fb..4e373239d 100644
--- a/npm-packages/convex/src/react/use_query.test.ts
+++ b/npm-packages/convex/src/react/use_query.test.ts
@@ -86,6 +86,12 @@ describe("useQuery types", () => {
       args: { _arg: "asdf" },
     });
 
+    useQuery({
+      query: api.module.args,
+      args: { anyarg: 0 },
+      skip: true,
+    });
+
     useQuery({
       query: api.module.args,
       args: { _arg: "asdf" },

From 22569bb0c3850d556b6cf41b2f26bdb6c71726bd Mon Sep 17 00:00:00 2001
From: Ian Macartney <ianhmacartney@gmail.com>
Date: Thu, 20 Nov 2025 19:30:37 -0800
Subject: [PATCH 2/2] still doesn't work

---
 npm-packages/convex/src/react/client.ts         | 2 +-
 npm-packages/convex/src/react/use_query.test.ts | 6 ++++--
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/npm-packages/convex/src/react/client.ts b/npm-packages/convex/src/react/client.ts
index 65fde6e7b..b60aa1ef8 100644
--- a/npm-packages/convex/src/react/client.ts
+++ b/npm-packages/convex/src/react/client.ts
@@ -812,7 +812,7 @@ export type UseQueryOptions<Query extends FunctionReference<"query">> = (
   | (QueryOptions<Query> & { skip?: false })
   | {
       query: Query;
-      args?: NoInfer<unknown>;
+      args?: unknown;
       skip: true;
     }
 ) & {
diff --git a/npm-packages/convex/src/react/use_query.test.ts b/npm-packages/convex/src/react/use_query.test.ts
index 4e373239d..7caa70fde 100644
--- a/npm-packages/convex/src/react/use_query.test.ts
+++ b/npm-packages/convex/src/react/use_query.test.ts
@@ -86,10 +86,12 @@ describe("useQuery types", () => {
       args: { _arg: "asdf" },
     });
 
+    const userId = undefined as string | undefined;
+
     useQuery({
       query: api.module.args,
-      args: { anyarg: 0 },
-      skip: true,
+      args: { _arg: userId },
+      skip: !userId,
     });
 
     useQuery({