useRead

Basic Usage

function UserList() {
  const { data, loading, error, trigger } = useRead(
    (api) => api("users").GET()
  );

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {data?.map((user) => <li key={user.id}>{user.name}</li>)}
    </ul>
  );
}

With Query Parameters

const { data, input } = useRead(
  (api) => api("users").GET({ query: { page: 1, limit: 10 } }),
  {
    enabled: isReady,
    tags: ["users", "dashboard"],
  }
);

Custom Tags

By default, a tag is auto-generated from the resolved path. You can override with custom tags:

// Auto-generated tag (default)
useRead((api) => api("users/:id/posts").GET({ params: { id: "123" } }));
// → tag: "users/123/posts"

// Single custom tag
useRead((api) => api("users/:id/posts").GET({ params: { id: "123" } }), {
  tags: "user-posts",
});
// → tag: "user-posts"

// Multiple custom tags
useRead((api) => api("posts").GET(), {
  tags: ["posts", "dashboard"],
});
// → tags: ["posts", "dashboard"]

Options

Option	Type	Default	Description
`enabled`	`boolean`	`true`	Whether to fetch automatically
`tags`	`string \| string[]`	-	Custom tags (overrides auto-generated tag)
+ plugin options	-	-	Options from installed plugins

Returns

Property	Type	Description
`data`	`TData \| undefined`	Response data
`error`	`TError \| undefined`	Error if request failed
`loading`	`boolean`	True during initial load
`fetching`	`boolean`	True during any fetch
`trigger`	`(options?) => Promise`	Manually trigger fetch with optional overrides
`abort`	`() => void`	Abort current request
`input`	`object`	The request input (query, body, params)
`meta`	`object`	Plugin-provided metadata

Trigger with Override Options

The trigger function accepts optional parameters to override the request:

const { data, trigger } = useRead((api) =>
  api("users/:id").GET({ params: { id: "1" } })
);

// Refetch with same params
trigger();

// Fetch with different params
trigger({ params: { id: "2" } });

// Override query parameters
trigger({ query: { include: "profile" } });

// Force refetch (bypass cache)
trigger({ force: true });

// Combine overrides
trigger({ params: { id: "3" }, query: { include: "posts" }, force: true });

You should avoid using custom options with trigger as much as possible. Most of the time, you can achieve the same effect by changing the enabled and input parameters in the initial request.

Trigger Options

Option	Type	Default	Description
`params`	`object`	-	Override URL path parameters
`query`	`object`	-	Override query string parameters
`body`	`unknown`	-	Override request body
`force`	`boolean`	`false`	Bypass cache and force fresh fetch

On-Demand Fetching

For cases where you don't want to fetch on mount (like download or print), use enabled: false and call trigger manually:

function DownloadReport() {
  const { data, loading, trigger } = useRead(
    (api) => api("reports/:id").GET({ params: { id: "" } }), // placeholder
    { enabled: false }
  );

  const handleDownload = async (reportId: string) => {
    const { data } = await trigger({ params: { id: reportId } });
    if (data) {
      // Process the downloaded report
      downloadFile(data.url, data.filename);
    }
  };

  return (
    <div>
      <button onClick={() => handleDownload("monthly")} disabled={loading}>
        Download Monthly Report
      </button>
      <button onClick={() => handleDownload("yearly")} disabled={loading}>
        Download Yearly Report
      </button>
    </div>
  );
}

On this page