@gadgetinc/react 

The @gadgetinc/react package provides React hooks for calling your Gadget app's auto-generated API.

1import { useFindMany, useAction } from "@gadgetinc/react";
2
3// your app's auto-generated API client
4import { api } from "../api";
5
6function WidgetDeleter() {
7  // `useFindMany` executes a backend fetch to get a list of widgets from the backend.
8  const [{ data, fetching, error }, refresh] = useFindMany(api.widget, {
9    select: {
10      id: true,
11      name: true,
12    },
13  });
14
15  // `useAction` sets up a mutation we can run to delete a specific widget when a user clicks a button
16  const [_, deleteWidget] = useAction(api.widget.delete);
17
18  if (fetching) return "Loading...";
19
20  return (
21    <ul>
22      {data?.map((widget) => (
23        <li>
24          {widget.name}
25          <button onClick={() => deleteWidget({ id: widget.id })}>Delete</button>
26        </li>
27      ))}
28    </ul>
29  );
30}

1import { useFindMany, useAction } from "@gadgetinc/react";
2
3// your app's auto-generated API client
4import { api } from "../api";
5
6function WidgetDeleter() {
7  // `useFindMany` executes a backend fetch to get a list of widgets from the backend.
8  const [{ data, fetching, error }, refresh] = useFindMany(api.widget, {
9    select: {
10      id: true,
11      name: true,
12    },
13  });
14
15  // `useAction` sets up a mutation we can run to delete a specific widget when a user clicks a button
16  const [_, deleteWidget] = useAction(api.widget.delete);
17
18  if (fetching) return "Loading...";
19
20  return (
21    <ul>
22      {data?.map((widget) => (
23        <li>
24          {widget.name}
25          <button onClick={() => deleteWidget({ id: widget.id })}>Delete</button>
26        </li>
27      ))}
28    </ul>
29  );
30}

Key features 

1. Rule-obeying hooks for reading and writing data from a backend that handle all request lifecycle and auth like useFindOne, useAction, and useFetch
2. Full type safety for inputs and outputs driven by each Gadget app's backend schema, including over dynamic selections
3. A full-featured, GraphQL-powered nested object selection system using the select option
4. Data hydrations that return useful objects like Date

Installation 

See the installation instructions for your app's API.

Provider Setup 

Your React application must be wrapped in the Provider component from this library for the hooks to function properly. No other wrappers (like urql's) are necessary.

Example:

1// import the API client for your specific application from your client package, be sure to replace this package name with your own
2import { Client } from "@gadget-client/example-app-slug";
3// import the required Provider object and some example hooks from this package
4import { Provider } from "@gadgetinc/react";
5
6// instantiate the API client for our app
7const api = new Client({ authenticationMode: { browserSession: true } });
8
9export const MyApp = (props: { children: React.ReactNode }) => {
10  // wrap the application in the <Provider> so the hooks can find the current client
11  return <Provider api={api}>{props.children}</Provider>;
12};

1// import the API client for your specific application from your client package, be sure to replace this package name with your own
2import { Client } from "@gadget-client/example-app-slug";
3// import the required Provider object and some example hooks from this package
4import { Provider } from "@gadgetinc/react";
5
6// instantiate the API client for our app
7const api = new Client({ authenticationMode: { browserSession: true } });
8
9export const MyApp = (props: { children: React.ReactNode }) => {
10  // wrap the application in the <Provider> so the hooks can find the current client
11  return <Provider api={api}>{props.children}</Provider>;
12};

Client side vs Server side React 

The @gadgetinc/react package is intended for use on the client-side only. The hooks provided by this package make requests from your app's frontend directly to your Gadget app's backend from the browser. If you want to use server-side rendering, you can use your framework's server-side data loader support and make imperative calls with your API client object.

Hooks 

useFindOne() 

useFindOne(manager: ModelFinder, id: string, options: SingleFinderOptions = {}): [{data, fetching, error}, refetch]

useFindOne fetches one record from your Gadget database with a given id.

1import React from "react";
2import { useFindOne } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const ShowWidgetName = (props: { id: string }) => {
6  const [{ data, fetching, error }, _refetch] = useFindOne(api.widget, props.id);
7
8  if (fetching) return "Loading...";
9  if (error) return `Error loading data: ${error}`;
10  return <span className="widget-name">{data?.name}</span>;
11};

1import React from "react";
2import { useFindOne } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const ShowWidgetName = (props: { id: string }) => {
6  const [{ data, fetching, error }, _refetch] = useFindOne(api.widget, props.id);
7
8  if (fetching) return "Loading...";
9  if (error) return `Error loading data: ${error}`;
10  return <span className="widget-name">{data?.name}</span>;
11};

Parameters 

• manager: The model manager for the model you want to find a record of. Required. Example: api.widget, or api.shopifyProduct
• id: The backend id of the record you want to find. Required.
• options: Options for making the call to the backend. Not required, and all keys are optional.
  • select: A list of fields and subfields to select. See select option
  • requestPolicy: The urql request policy to make the request with. See urql's docs
  • pause: Set to true to disable this hook. See urql's docs
  • suspense: Should this hook suspend when fetching data. See suspense

Returns 

useFindOne returns two values: a result object with the data, fetching, and error keys for inspecting in your React component's output, and a refetch function to trigger a refresh of the hook's data.

• data: GadgetRecord | null: The record fetched from the backend. Is null while the data is being loaded, or if the record wasn't found.
• fetching: boolean: A boolean describing if the hook is currently requesting data from the backend.
• error: Error | null: An error from the client or server side, if encountered during the request. Will contain an error if the record isn't found by id. See the errors section.

useFindOne expects a record with the given id to be found in the backend database, and will return an error in the error property if no record with this id is found.

useFindOne can select only some fields from the backend model with the select option:

1import React from "react";
2import { useFindOne } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const OnlySomeWidgetFields = (props: { id: string }) => {
6  // fetch only the widget id and name fields
7  const [{ data, fetching, error }, _refetch] = useFindOne(api.widget, props.id, {
8    select: {
9      id: true,
10      name: true,
11    },
12  });
13
14  return (
15    <span className="widget-name">
16      {data?.id}: {data?.name}
17    </span>
18  );
19};

1import React from "react";
2import { useFindOne } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const OnlySomeWidgetFields = (props: { id: string }) => {
6  // fetch only the widget id and name fields
7  const [{ data, fetching, error }, _refetch] = useFindOne(api.widget, props.id, {
8    select: {
9      id: true,
10      name: true,
11    },
12  });
13
14  return (
15    <span className="widget-name">
16      {data?.id}: {data?.name}
17    </span>
18  );
19};

useMaybeFindOne() 

useMaybeFindOne(manager: ModelFinder, id: string, options: SingleFinderOptions = {}): [{data, fetching, error}, refetch]

useMaybeFindOne fetches one record from your Gadget database with a given id.

1import React from "react";
2import { useMaybeFindOne } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const ShowWidgetName = (props: { id: string }) => {
6  const [{ data, fetching, error }, _refetch] = useMaybeFindOne(api.widget, props.id);
7
8  if (fetching) return "Loading...";
9  if (error) return `Error loading data: ${error}`;
10  if (data) {
11    return <span className="widget-name">{data.name}</span>;
12  } else {
13    return "No widget found";
14  }
15};

1import React from "react";
2import { useMaybeFindOne } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const ShowWidgetName = (props: { id: string }) => {
6  const [{ data, fetching, error }, _refetch] = useMaybeFindOne(api.widget, props.id);
7
8  if (fetching) return "Loading...";
9  if (error) return `Error loading data: ${error}`;
10  if (data) {
11    return <span className="widget-name">{data.name}</span>;
12  } else {
13    return "No widget found";
14  }
15};

useMaybeFindOne will return data: null and error: null if no record with the given id is found in the backend database. useMaybeFindOne otherwise behaves identically to useFindOne, and accepts the same options.

useFindMany() 

useFindMany(manager: ModelFinder, options: ManyFinderOptions = {}): [{data, fetching, error}, refetch]

useFindMany fetches a page of records from your Gadget database, optionally sorted, filtered, or searched.

1import React from "react";
2import { useFindMany } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const ShowWidgetNames = () => {
6  const [{ data, fetching, error }, _refetch] = useFindMany(api.widget);
7
8  if (fetching) return "Loading...";
9  if (error) return `Error loading data: ${error}`;
10  return (
11    <ul>
12      {data?.map((widget) => (
13        <li key={widget.id}>{widget.name}</li>
14      ))}
15    </ul>
16  );
17};

1import React from "react";
2import { useFindMany } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const ShowWidgetNames = () => {
6  const [{ data, fetching, error }, _refetch] = useFindMany(api.widget);
7
8  if (fetching) return "Loading...";
9  if (error) return `Error loading data: ${error}`;
10  return (
11    <ul>
12      {data?.map((widget) => (
13        <li key={widget.id}>{widget.name}</li>
14      ))}
15    </ul>
16  );
17};

Parameters 

• manager: The model manager for the model you want to find a page of records for. Required. Example: api.widget, or api.shopifyProduct
• options: Options for making the call to the backend. Not required and all keys are optional.
  • select: A list of fields and subfields to select. See the select option docs.
  • filter: A list of filters to limit the set of returned records. Optional. See the Model Filtering section in your application's API documentation to see the available filters for your models.
  • search: A search string to match backend records against. Optional. See the Model Searching section in your application's API documentation to see the available search syntax.
  • sort: A sort order to return backend records by. Optional. See the sorting section in your application's API documentation for more info.
  • first & after: Pagination arguments to pass to fetch a subsequent page of records from the backend. first should hold a record count and after should hold a string cursor retrieved from the pageInfo of the previous page of results. See the pagination section in your application's API documentation for more info.
  • last & before: Pagination arguments to pass to fetch a subsequent page of records from the backend. last should hold a record count and before should hold a string cursor retrieved from the pageInfo of the previous page of results. See the pagination section in your application's API documentation for more info.
  • live: Should this hook re-render when data changes on the backend. See the live option docs.
  • requestPolicy: The urql request policy to make the request with. See urql's docs
  • pause: Should the hook make a request right now or not. See urql's docs
  • suspense: Should this hook suspend when fetching data. See suspense for more info

Returns 

useFindMany returns two values: a result object with the data, fetching, and error keys for use in your React component's output, and a refetch function to trigger a refresh of the hook's data.

• data: GadgetRecordList | null: The resulting page of records fetched from the backend for your model, once they've arrived
• fetching: boolean: A boolean describing if the hook is currently making a request to the backend.
• error: Error | null: An error from the client or server side, if encountered during the request. See the errors section.

Without any options, useFindMany will fetch the first page of backend records sorted by id.

useFindMany accepts the select option to allow customization of which fields are returned:

1import React from "react";
2import { useFindMany } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const OnlySomeWidgetFields = () => {
6  // fetch only the widget id and name fields
7  const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
8    select: {
9      id: true,
10      name: true,
11    },
12  });
13
14  if (fetching) return "Loading...";
15  if (error) return `Error loading data: ${error}`;
16  return (
17    <ul>
18      {data?.map((widget) => (
19        <li key={widget.id}>{widget.name}</li>
20      ))}
21    </ul>
22  );
23};

1import React from "react";
2import { useFindMany } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const OnlySomeWidgetFields = () => {
6  // fetch only the widget id and name fields
7  const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
8    select: {
9      id: true,
10      name: true,
11    },
12  });
13
14  if (fetching) return "Loading...";
15  if (error) return `Error loading data: ${error}`;
16  return (
17    <ul>
18      {data?.map((widget) => (
19        <li key={widget.id}>{widget.name}</li>
20      ))}
21    </ul>
22  );
23};

useFindMany accepts a filter option to limit which records are returned from the backend. For example, we can filter to return only widgets created since the start of 2022:

1// fetch only the widgets created recently
2const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
3  filter: {
4    createdAt: { greaterThan: new Date(2022, 1, 1) },
5  },
6});

1// fetch only the widgets created recently
2const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
3  filter: {
4    createdAt: { greaterThan: new Date(2022, 1, 1) },
5  },
6});

See your app's API reference for more information on which filters are available on what models.

useFindMany accepts a sort option to change the order of the records that are returned. For example, we can sort returned widgets by the createdAt field:

1// return the most recently created widgets first
2const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
3  sort: {
4    createdAt: "Descending",
5  },
6});

1// return the most recently created widgets first
2const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
3  sort: {
4    createdAt: "Descending",
5  },
6});

useFindMany accepts a search option to limit the fetched records to only those matching a given search query. For example, we can search all the backend widgets for those matching the string "penny" in any searchable field:

// return widgets with "penny" in any searchable field
const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
  search: "penny",
});

// return widgets with "penny" in any searchable field
const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
  search: "penny",
});

See your app's API reference for more information on the search query syntax and which fields are searchable.

useFindMany accepts a live option to subscribe to changes in the backend data returned, which will trigger re-renders of your react components as that data changes. For example, we can show an up-to-date view of the first page of backend widgets:

// will update when new widgets are created or on-screen widgets are updated
const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
  live: true,
});

// will update when new widgets are created or on-screen widgets are updated
const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
  live: true,
});

useFindMany accepts pagination arguments for getting the second, third, etc page of results from the backend beyond just the first page. Gadget applications use Relay Cursor style GraphQL pagination, where a second page is fetched by asking for the next x many results after a cursor returned with the first page.

1// return the first 10 results after some cursor from somewhere else
2const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
3  first: 10,
4  after: "some-cursor-value",
5});
6
7// data is a GadgetRecordList object, which has extra properties for inquiring about the pagination state
8// the current page's start and end cursor are available for use to then make later requests for different pages
9const {
10  // string used for forward pagination, pass to the `after:` variable
11  endCursor,
12  // string used for backwards pagination, pass to the `before:` variable
13  startCursor,
14
15  // `data` also reports if there are more pages for fetching
16  // boolean indicating if there is another page to fetch after the `endCursor`
17  hasNextPage,
18  // boolean indicating if there is another page to fetch before the `startCursor`
19  hasPreviousPage,
20} = data;

1// return the first 10 results after some cursor from somewhere else
2const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
3  first: 10,
4  after: "some-cursor-value",
5});
6
7// data is a GadgetRecordList object, which has extra properties for inquiring about the pagination state
8// the current page's start and end cursor are available for use to then make later requests for different pages
9const {
10  // string used for forward pagination, pass to the `after:` variable
11  endCursor,
12  // string used for backwards pagination, pass to the `before:` variable
13  startCursor,
14
15  // `data` also reports if there are more pages for fetching
16  // boolean indicating if there is another page to fetch after the `endCursor`
17  hasNextPage,
18  // boolean indicating if there is another page to fetch before the `startCursor`
19  hasPreviousPage,
20} = data;

An easy way to do pagination is using React state, or for a better user experience, using the URL with whatever router system works for your application. We use React state to demonstrate pagination in this example:

1import React, { useState } from "react";
2import { useFindMany } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const WidgetPaginator = () => {
6  // store the current cursor in the backend data
7  const [cursor, setCursor] = useState<string | undefined>(undefined);
8
9  // pass the current cursor to the `after:` variable, telling the backend to return data after this cursor
10  const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
11    first: 20,
12    after: cursor,
13  });
14
15  if (fetching) return "Loading...";
16  if (error) return `Error loading data: ${error}`;
17
18  return (
19    <>
20      <ul>
21        {data?.map((widget) => (
22          <li key={widget.id}>{widget.name}</li>
23        ))}
24      </ul>
25      <button
26        onClick={() => {
27          // update the cursor, which will trigger a refetch of the next page and rerender with a new `data` object
28          setCursor(data?.endCursor);
29        }}
30        disabled={!data?.hasNextPage}
31      >
32        Next page
33      </button>
34    </>
35  );
36};

1import React, { useState } from "react";
2import { useFindMany } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const WidgetPaginator = () => {
6  // store the current cursor in the backend data
7  const [cursor, setCursor] = useState<string | undefined>(undefined);
8
9  // pass the current cursor to the `after:` variable, telling the backend to return data after this cursor
10  const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
11    first: 20,
12    after: cursor,
13  });
14
15  if (fetching) return "Loading...";
16  if (error) return `Error loading data: ${error}`;
17
18  return (
19    <>
20      <ul>
21        {data?.map((widget) => (
22          <li key={widget.id}>{widget.name}</li>
23        ))}
24      </ul>
25      <button
26        onClick={() => {
27          // update the cursor, which will trigger a refetch of the next page and rerender with a new `data` object
28          setCursor(data?.endCursor);
29        }}
30        disabled={!data?.hasNextPage}
31      >
32        Next page
33      </button>
34    </>
35  );
36};

useFindFirst() 

useFindFirst(manager: ModelFinder, options: FindManyOptions = {}): [{data, fetching, error}, refetch]

useFindFirst fetches the first record from your backend Gadget database that matches the given filter, sort, and search.

1import React from "react";
2import { useFindFirst } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const MostRecentPublishedPost = (props: { id: string }) => {
6  // request the first record from the backend where publishedAt is set and with the most recent publishedAt value
7  const [{ data, fetching, error }, _refetch] = useFindFirst(api.blogPost, {
8    filter: { publishedAt: { isSet: true } },
9    sort: { publishedAt: "Descending" },
10  });
11
12  if (fetching) return "Loading...";
13  if (error) return `Error loading data: ${error}`;
14  return <span className="banner">Check out our most recent blog post titled {data?.title}</span>;
15};

1import React from "react";
2import { useFindFirst } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const MostRecentPublishedPost = (props: { id: string }) => {
6  // request the first record from the backend where publishedAt is set and with the most recent publishedAt value
7  const [{ data, fetching, error }, _refetch] = useFindFirst(api.blogPost, {
8    filter: { publishedAt: { isSet: true } },
9    sort: { publishedAt: "Descending" },
10  });
11
12  if (fetching) return "Loading...";
13  if (error) return `Error loading data: ${error}`;
14  return <span className="banner">Check out our most recent blog post titled {data?.title}</span>;
15};

Parameters 

• manager: The model manager for the model you want to find a page of records for. Required. Example: api.widget, or api.shopifyProduct
• options: Options for making the call to the backend. Not required and all keys are optional.
  • select: A list of fields and subfields to select. See the select option docs. Optional.
  • filter: A list of filters to find a record matching. Optional. See the Model Filtering section in your application's API documentation to see the available filters for your models.
  • search: A search string to find a record matching. Optional. See the Model Searching section in your application's API documentation to see the available search syntax.
  • sort: A sort order to order the backend records by. useFindFirst will only return the first record matching the given search and filter, so sort can be used to break ties and select a specific record. Optional. See the sorting section in your application's API documentation for more info.
  • live: Should this hook re-render when data changes on the backend. See the live option docs.
  • requestPolicy: The urql request policy to make the request with. See urql's docs
  • pause: Should the hook make a request right now or not. See urql's docs
  • suspense: Should this hook suspend when fetching data. See suspense for more info

Returns 

useFindFirst returns two values: a result object with the data, fetching, and error keys for inspecting in your React component's output, and a refetch function to trigger a refresh of the hook's data.

• data: GadgetRecord | null: The record fetched from the backend. Is null while the data is being loaded, or if a matching record wasn't found.
• fetching: boolean: A boolean describing if the hook is currently making a request to the backend.
• error: Error | null: An error from the client or server side, if encountered during the request. Will contain an error if the first record isn't found. See the errors section.

If no record is found matching the conditions, useFindFirst will return {data: null, error: new MissingDataError}.

Without any options, useFindFirst will fetch the first matching record and cause your component to rerender as the fetch happens and when the data or error arrives.

useFindFirst can only select some of the fields from the backend model with select:

1// fetch the first upside down widget, and only it's id and name fields
2const [{ data }] = useFindFirst(api.widget, {
3  filter: {
4    state: { equals: "upsideDown" },
5  },
6  select: {
7    id: true,
8    name: true,
9  },
10});

1// fetch the first upside down widget, and only it's id and name fields
2const [{ data }] = useFindFirst(api.widget, {
3  filter: {
4    state: { equals: "upsideDown" },
5  },
6  select: {
7    id: true,
8    name: true,
9  },
10});

useFindFirst can subscribe to changes in the returned data from the backend with the live option, and re-render when the backend data changes:

1// fetch the first upside down widget, and re-render if it's data changes
2const [{ data }] = useFindFirst(api.widget, {
3  filter: {
4    state: { equals: "upsideDown" },
5  },
6  live: true,
7});

1// fetch the first upside down widget, and re-render if it's data changes
2const [{ data }] = useFindFirst(api.widget, {
3  filter: {
4    state: { equals: "upsideDown" },
5  },
6  live: true,
7});

useFindBy() 

useFindBy(findFunction: ModelFindFunction, fieldValue: any, options: FindByOptions = {}): [{data, fetching, error}, refetch]

useFindBy fetches one record from your backend looked up by a specific field and value. useFindBy requires a by-field record finder like .findBySlug or .findByEmail to exist for your model, which are generated by adding a Unique Validations to a field.

1import React from "react";
2import { useFindBy } from "@gadgetinc/react";
3import { api } from "../api";
4
5// get a slug from the URL or similar, and look up a post record by this slug
6export const PostBySlug = (props: { slug: string }) => {
7  const [{ data, fetching, error }, _refetch] = useFindBy(api.blogPost.findBySlug, props.slug);
8
9  if (fetching) return "Loading...";
10  if (error) return `Error loading data: ${error}`;
11  return (
12    <>
13      <h2>{data?.title}</h2>
14      <p>{data?.body}</p>
15    </>
16  );
17};

1import React from "react";
2import { useFindBy } from "@gadgetinc/react";
3import { api } from "../api";
4
5// get a slug from the URL or similar, and look up a post record by this slug
6export const PostBySlug = (props: { slug: string }) => {
7  const [{ data, fetching, error }, _refetch] = useFindBy(api.blogPost.findBySlug, props.slug);
8
9  if (fetching) return "Loading...";
10  if (error) return `Error loading data: ${error}`;
11  return (
12    <>
13      <h2>{data?.title}</h2>
14      <p>{data?.body}</p>
15    </>
16  );
17};

Parameters 

• findFunction: The model finder function from your application's API client for finding records by a specific field. Gadget generates these finder functions for the fields where they are available. Changes to your Gadget backend schema may be required to get these to exist. Required. Example: api.widget.findBySlug, or api.user.findByEmail.
• fieldValue: The value of the field to search for a record using. This is which slug or email you'd pass to api.widget.findBySlug or api.user.findByEmail.
• options: Options for making the call to the backend. Not required and all keys are optional.
  • select: A list of fields and subfields to select. See the select option docs.
  • live: Should this hook re-render when data changes on the backend. See the live option docs.
  • requestPolicy: The urql request policy to make the request with. See urql's docs
  • pause: Should the hook make a request right now or not. See urql's docs
  • suspense: Should this hook suspend when fetching data. See suspense for more info

Returns 

useFindBy returns two values: a result object with the data, fetching, and error keys for inspecting in your React component's output, and a refetch function to trigger a refresh of the hook's data.

• data: GadgetRecord | null: The record fetched from the backend. Is null while the data is being loaded, or if a matching record wasn't found for the given fieldValue.
• fetching: boolean: A boolean describing if the hook is currently making a request to the backend.
• error: Error | null: An error from the client or server side, if encountered during the request. Will contain an error if a matching record isn't found. See the errors section.

If no record is found matching the conditions, then the returned object will have null for the data. useFindBy(api.widget.findByEmail, "[email protected]") is the React equivalent of api.widget.findByEmail("[email protected]")

Without any options, useFindBy will fetch the record with the given field value, and cause your component to rerender as the fetch happens and when the data or error arrives:

1import React from "react";
2import { useFindBy } from "@gadgetinc/react";
3import { api } from "../api";
4
5// get a slug from the URL or similar, and look up a post record by this slug
6export const PostBySlug = (props: { slug: string }) => {
7  const [{ data, fetching, error }, _refetch] = useFindBy(api.blogPost.findBySlug, props.slug);
8
9  if (fetching) return "Loading...";
10  if (error) return `Error loading data: ${error}`;
11  return (
12    <>
13      <h2>{data?.title}</h2>
14      <p>{data?.body}</p>
15    </>
16  );
17};

1import React from "react";
2import { useFindBy } from "@gadgetinc/react";
3import { api } from "../api";
4
5// get a slug from the URL or similar, and look up a post record by this slug
6export const PostBySlug = (props: { slug: string }) => {
7  const [{ data, fetching, error }, _refetch] = useFindBy(api.blogPost.findBySlug, props.slug);
8
9  if (fetching) return "Loading...";
10  if (error) return `Error loading data: ${error}`;
11  return (
12    <>
13      <h2>{data?.title}</h2>
14      <p>{data?.body}</p>
15    </>
16  );
17};

useFindBy can take options that allow the customization of which fields are returned:

// fetch only a post id and title fields
const [{ data, fetching, error }, _refetch] = useFindBy(api.blogPost.findBySlug, "some-slug", { select: { id: true, title: true } });

// fetch only a post id and title fields
const [{ data, fetching, error }, _refetch] = useFindBy(api.blogPost.findBySlug, "some-slug", { select: { id: true, title: true } });

The refetch function returned as the second element can be executed in order to trigger a refetch of the most up to date data from the backend. See urql's docs on re-executing queries for more information.

useMaybeFindFirst() 

useMaybeFindFirst(manager: ModelFinder, options: FindManyOptions = {}): [{data, fetching, error}, refetch]

useMaybeFindFirst fetches the first record from your backend Gadget database that matches the given filter, sort, and search parameters.

1import React from "react";
2import { useMaybeFindFirst } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const MostRecentPublishedPost = (props: { id: string }) => {
6  // request the first record from the backend where publishedAt is set and with the most recent publishedAt value
7  const [{ data, fetching, error }, _refetch] = useMaybeFindFirst(api.blogPost, {
8    filter: { publishedAt: { isSet: true } },
9    sort: { publishedAt: "Descending" },
10  });
11
12  if (fetching) return "Loading...";
13  if (error) return `Error loading data: ${error}`;
14  if (data) {
15    return <span className="banner">Check out our most recent blog post titled {data.title}</span>;
16  } else {
17    // no first record found
18    return null;
19  }
20};

1import React from "react";
2import { useMaybeFindFirst } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const MostRecentPublishedPost = (props: { id: string }) => {
6  // request the first record from the backend where publishedAt is set and with the most recent publishedAt value
7  const [{ data, fetching, error }, _refetch] = useMaybeFindFirst(api.blogPost, {
8    filter: { publishedAt: { isSet: true } },
9    sort: { publishedAt: "Descending" },
10  });
11
12  if (fetching) return "Loading...";
13  if (error) return `Error loading data: ${error}`;
14  if (data) {
15    return <span className="banner">Check out our most recent blog post titled {data.title}</span>;
16  } else {
17    // no first record found
18    return null;
19  }
20};

useMaybeFindFirst returns data: null if no record is found in the backend database, and otherwise works identically to useFindFirst. See useFindFirst for more details on the options useMaybeFindFirst accepts.

useAction() 

useAction(actionFunction: ModelActionFunction, options: UseActionOptions = {}): [{data, fetching, error}, refetch]

1import React from "react";
2import { useAction } from "@gadgetinc/react";
3import { api } from "../api";
4
5export const CreatePost = () => {
6  const [{ data, fetching, error }, createBlogPost] = useAction(api.blogPost.create);
7
8  return (
9    <button
10      onClick={() => {
11        createBlogPost({
12          title: "New post created from React",
13        });
14      }}
15    >
16      Create a post
17    </button>
18  );
19};