@gadgetinc/react 

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

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

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 Dates

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:

JavaScript
Copy
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) => {
10  // wrapp the application in the <Provider> so the hooks can find the current client
11  return <Provider api={api}>{props.children}</Provider>;
12};

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.

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

Parameters 

• manager: The model manager you 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:

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

useMaybeFindOne() 

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

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

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

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.

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

Parameters 

• manager: The model manager you 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 Model 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 Model 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:

JavaScript
Copy
1export const OnlySomeWidgetFields = (props: { id: string }) => {
2  // fetch only the widget id and name fields
3  const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
4    select: { id: true, name: true },
5  });
6
7  if (fetching) return "Loading...";
8  if (error) return `Error loading data: ${error}`;
9  return (
10    <ul>
11      {data.map((widget) => (
12        <li key={widget.id}>{widget.name}</li>
13      ))}
14    </ul>
15  );
16};

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:

JavaScript
Copy
1// fetch only the widgets created recently
2const [{ data, fetching, error }, _refetch] = useFindMany(api.widget, {
3  filter: {
4    createdAt: { greaterThan: new Date(2022, 01, 01) },
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:

JavaScript
Copy
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:

JavaScript
Copy
// return the most recently created widgets first
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:

JavaScript
Copy
// 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.

JavaScript
Copy
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
9data.endCursor; // => string, used for forward pagination, pass to the `after:` variable
10data.startCursor; // => string, used for backwards pagination, pass to the `before:` variable
11// data also reports if there are more pages for fetching
12data.hasNextPage; // => boolean, true if there is another page to fetch after the `endCursor`
13data.hasPreviousPage; // => boolean, true if there is another page to fetch before the `startCursor`

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:

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

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.

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

Parameters 

• manager: The model manager you 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:

JavaScript
Copy
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:

JavaScript
Copy
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.

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

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:

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

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

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

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.

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

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]

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

useAction is a hook for running a backend action on one record of a Gadget model. useAction must be passed an action function from an instance of your application's generated API client. Options:

Parameters 

• actionFunction: The model action function from your application's API client for acting on records. Gadget generates these action functions for each action defined on backend Gadget models. Required. Example: api.widget.create, or api.user.update or api.blogPost.publish.
• 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.
  • 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 

useAction returns two values: a result object with the data, fetching, and error keys for inspecting in your React component's output, and a act function to actually run the backend action. useAction is a rule-following React hook that wraps action execution, which means it doesn't just run the action as soon as the hook is invoked. Instead, useAction returns a configured function that will actually run the action, which you need to call in response to some user event. The act function accepts the action inputs as arguments -- not useAction itself.

useAction's result will return the data, fetching, and error details for the most recent execution of the action.

• data: GadgetRecord | null: The record fetched from the backend after a mutation. Is null while before the mutation is run and while it is currently ongoing.
• 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 mutation. Will contain an error if the client passed invalid data, if the server failed to complete the action, or if a network error was encountered. See the Errors section.

For example, we can create a button that creates a post when clicked, and then shows the post once it has been created:

JavaScript
Copy
1import React from "react";
2import { api } from "../api";
3
4export const CreatePost = () => {
5  const [{ data, fetching, error }, createBlogPost] = useAction(api.blogPost.create);
6
7  // deal with all the states of the result object
8  if (fetching) return "Loading...";
9  if (error) return `Error loading data: ${error}`;
10
11  if (!data) {
12    return (
13      <button
14        onClick={() => {
15          createBlogPost({
16            title: "New post created from React",
17          });
18        }}
19      >
20        Create a post
21      </button>
22    );
23  } else {
24    return (
25      <>
26        <h2>{data.title}</h2>
27        <p>{data.body}</p>
28      </>
29    );
30  }
31};

We can also run actions on existing models by passing the id: in with the action parameters:

JavaScript
Copy
1import React from "react";
2import { api } from "../api";
3
4export const UpdatePost = (props: { id: string }) => {
5  // invoke the `useAction` hook, getting back a result object and an action runner function every render
6  const [{ data, fetching, error }, updateBlogPost] = useAction(api.blogPost.update);
7  const [title, setTitle] = useState("");
8
9  if (fetching) return "Loading...";
10  if (error) return `Error loading data: ${error}`;
11
12  return (
13    <form
14      onSubmit={() => {
15        // pass the id of the blog post we're updating as one parameter, and the new post attributes as another
16        updateBlogPost({
17          id: props.id,
18          title,
19        });
20      }}
21    >
22      <label>Title</label>
23      <input
24        type="text"
25        value={title}
26        onChange={(event) => setTitle(event.target.value)}
27      />
28      <input type="submit">Submit</input>
29    </form>
30  );
31};

useAction can take options that allow the customization of which fields are returned on the acted-upon record:

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

useGlobalAction() 

useGlobalAction(actionFunction: GlobalActionFunction, options: UseGlobalActionOptions = {}): [{data, fetching, error}, refetch]

useGlobalAction is a hook for running a backend Global Action.

JavaScript
Copy
1import React from "react";
2import { api } from "../api";
3
4export const PurgeData = () => {
5  const [{ data, fetching, error }, runPurge] = useGlobalAction(api.purgeData);
6
7  return (
8    <button
9      onClick={() => {
10        purgeData({ foo: "bar" });
11      }}
12    >
13      Purge data
14    </button>
15  );
16};

Parameters 

• globalActionFunction: The action function from your application's API client. Gadget generates these global action functions for each global action defined in your Gadget backend. Required. Example: api.runSync, or api.purgeData (corresponding to Global Actions named Run Sync or Purge Data).
• options: Options for making the call to the backend. Not required and all keys are optional.
  • 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

Returns 

useGlobalAction returns two values: a result object with the data, fetching, and error keys for inspecting in your React component's output, and an act function to actually run the backend global action. useGlobalAction is a rule-following React hook that wraps action execution, which means it doesn't just run the action as soon as the hook is invoked. Instead, useGlobalAction returns a configured function which you need to call in response to some event. This act function accepts the action inputs as arguments. useGlobalAction's result will return the data, fetching, and error details for the most recent execution of the action.

• data: Record<string, any> | null: The data returned by the global action from the backend. Is null while before the mutation is run and while it is currently ongoing.
• 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 mutation. Will contain an error if the client passed invalid data, if server failed to complete the mutation, or if a network error was encountered. See the Errors section.

For example, we can create a button that runs a Global Action called purgeData when clicked, and shows the result after it has been run:

JavaScript
Copy
1import React from "react";
2import { api } from "../api";
3
4export const PurgeData = () => {
5  const [{ data, fetching, error }, runPurge] = useGlobalAction(api.purgeData);
6
7  // deal with all the states of the result object
8  if (fetching) return "Loading...";
9  if (error) return `Error running global action: ${error}`;
10
11  if (!data) {
12    return (
13      <button
14        onClick={() => {
15          purgeData({ foo: "bar" });
16        }}
17      >
18        Purge data
19      </button>
20    );
21  } else {
22    return "Purge completed";
23  }
24};

useGet() 

useGet(singletonModelManager: SingletonModelManager, options: GetOptions = {}): [{data, fetching, error}, refetch]

useGet fetches a singleton record for an api.currentSomething style model manager. useGet fetches one global record, which is most often the current session.

JavaScript
Copy
1import React from "react";
2import { api } from "../api";
3
4export const CurrentSessionId = () => {
5  const [{ data, fetching, error }, _refetch] = useGet(api.currentSession);
6
7  if (fetching) return "Loading...";
8  if (error) return `Error loading data: ${error}`;
9  return (
10    <span>
11      Current session: {data.id} is {data.state}
12    </span>
13  );
14};

Parameters 

• singletonModelManager: The singleton model manager available on the generated API client for your application. The passed model manager must be one of the currentSomething model managers. useGet can't be used with other model managers that don't have a .get function. Example: api.currentSession.
• 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.
  • 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 

useGet 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 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 singleton record isn't found. See the Errors section.

useGet(api.currentSession) retrieves the current global session for the current browser

JavaScript
Copy
1import React from "react";
2import { api } from "../api";
3
4export const CurrentSessionId = () => {
5  const [{ data, fetching, error }, _refetch] = useGet(api.currentSession);
6
7  if (fetching) return "Loading...";
8  if (error) return `Error loading data: ${error}`;
9  return (
10    <span>
11      Current session: {data.id} is {data.state}
12    </span>
13  );
14};

useGet can take options which allow the customization of which fields are returned on the selected record:

JavaScript
Copy
// fetch only the session id and state fields
const [{ data, fetching, error }, _refetch] = useGet(api.currentSession, {
  select: { id: true, state: true },
});

The refetch function returned as the second element can be executed 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.

useEnqueue() 

useEnqueue(actionFunction: ModelActionFunction || GlobalActionFunction, actionInput, backgroundActionOptions = {}): [{error, fetching, handle}, enqueue]

useEnqueue facilitates the enqueuing of actions to be executed in the background.

web/components/CreateUserButton.jsx
JavaScript
Copy
1import { useEnqueue } from "react";
2import { api } from "../api";
3
4export function CreateUserButton(props: { name: string, email: string }) {
5  const [{ error, fetching, data, handle }, enqueue] = useEnqueue(api.user.create);
6
7  const onClick = () =>
8    enqueue(
9      {
10        // actionInput
11        name: props.name,
12        email: props.email,
13      },
14      {
15        // backgroundActionoptions
16        id: `send-email-action-${props.email}`,
17      }
18    );
19
20  return (
21    <>
22      {error && <>Failed to enqueue user create: {error.toString()}</>}
23      {fetching && <>Enqueuing action...</>}
24      {data && <>Enqueued action with background action id={handle.id}</>}
25      <button onClick={onClick}>Create user</button>
26    </>
27  );
28}

Parameters 

• actionFunction: ModelActionFunction || GlobalActionFunction: Either a model or global action.
• actionInput: Input | null: The parameters or data passed to a model or global action.
• backgroundActionOptions (optional): The options for how the background action runs, for more information check out the reference here.

Returns 

useEnqueue doesn't submit the background action when invoked but instead returns a function for enqueuing the action in response to the event.

useActionForm() 

useActionForm(actionFunction: ModelActionFunction, options: UseActionFormOptions = {}): UseActionFormResult

useActionForm manages form state for calling actions in your Gadget backend. useActionForm can fetch the record for editing, manage the state of the fields as the user changes them in a form, track validations and errors, and then call the action with the form data when the user submits the form. useActionForm can call Actions on models as well as Global Actions.

JavaScript
Copy
1import { useActionForm } from "@gadgetinc/react";
2import { api } from "../api";
3
4const PostForm = () => {
5  const { register, submit } = useActionForm(api.post.create);
6
7  return (
8    <form onSubmit={submit}>
9      <label htmlFor="title">Title</label>
10      <input id="title" type="text" {...register("post.title")} />
11
12      <label htmlFor="content">Content</label>
13      <textarea id="content" {...register("post.content")} />
14      <input type="submit" />
15    </form>
16  );
17};

Read more about building forms in the Frontend Forms guide.

Parameters 

• action: the Model Action or Global Action to call when submitting. Required.
• options: the configuration for the form

The options options object accepts the following options:

useActionForm's props input is very similar to useForm's from react-hook-form. For more docs on these props, see the react-hook-form docs.

Returns 

useActionForm returns a variety of functions and state for managing your form that most users destructure as they call it:

JavaScript
Copy
const { register, submit, error, reset, ...rest } = useActionForm(api.post.update, {
  defaultValues: { id: "123" },
});

The available result values are:

FormState object 

The FormState object returned by useActionForm includes the following properties:

For more on the FormState object, see the react-hook-form docs.

Missing options from react-hook-form 

Unlike react-hook-form, useActionForm manages the submission process to your backend action. You don't need to manually make a call to your action -- instead, call the submit function returned by useActionForm when you are ready to submit the form, and useActionForm will call the action.

Because the submission process is managed, useActionForm does not accept the handleSubmit option that react-hook-form does.

<Controller/> 

useActionForm's register function only works with uncontrolled components that conform to normal DOM APIs. For working with controlled components, like those from popular UI libraries such as @shopify/polaris, you must register these input components with a <Controller/> instead.

JavaScript
Copy
1import { TextField } from "@shopify/polaris";
2import { useActionForm, Controller } from "@gadgetinc/react";
3import { api } from "../api";
4
5const AllowedTagForm = () => {
6  const { submit, control } = useActionForm(api.allowedTag.create);
7
8  return (
9    <form onSubmit={submit}>
10      <Controller
11        name="keyword"
12        control={control}
13        required
14        render={({ field }) => {
15          // Functional components like the Polaris TextField do not allow for 'ref's to be passed in
16          // Remove it from the props passed to the TextField
17          const { ref, ...fieldProps } = field;
18          // Pass the field props down to the textField to set the value value and add onChange handlers
19          return (
20            <TextField
21              label="Keyword"
22              type="text"
23              autoComplete="off"
24              {...fieldProps}
25            />
26          );
27        }}
28      />
29    </form>
30  );
31};

<Controller/> accepts the following props:

For more information on <Controller/>, see the react-hook-form docs

useFetch() 

useFetch(path: string, options: RequestInit = {})

useFetch is a low-level hook for making an HTTP request to your Gadget backend's HTTP routes. useFetch preserves client-side authentication information by using api.fetch under the hood, which means fetches will use the same request identity as other GraphQL API calls using the other hooks.

JavaScript
Copy
1import { useFetch } from "@gadgetinc/react";
2
3export function UserByEmail(props) {
4  const [{ data, fetching, error }, refresh] = useFetch("/users/me", {
5    method: "GET",
6    headers: {
7      "content-type": "application/json",
8    },
9    json: true,
10  });
11
12  if (result.error) return <>Error: {result.error.toString()}</>;
13  if (result.fetching && !result.data) return <>Fetching...</>;
14  if (!result.data) return <>No user found with id={props.id}</>;
15
16  return <div>{result.data.name}</div>;
17}

Parameters 

• path: the server-side URL to fetch from. Corresponds to an HTTP route defined on in your backend Gadget app's routes folder
• options: options configuring the fetch call, corresponding exactly to those you might send with a normal fetch.
  • method: the request method, like "GET", "POST", etc. Defaults to "GET"
  • headers: the request headers, like { "content-type": "application/json" }
  • body: the request body to send to the server, like "hello" or JSON.stringify({foo: "bar"})
  • json: If true, expects the response to be returned as JSON, and parses it for convenience
  • stream:
    • If true, response will be a ReadableStream object, allowing you to work with the response as it arrives
    • If "string", will decode the response as a string and update data as the response arrives; this is useful when streaming responses from LLMs
  • onStreamComplete: a callback function that will be called with the final content when the streaming response is complete; this is only available when the stream: "string" option is set
  • sendImmediately: If true, sends the first fetch on component mount. If false, waits for the send function to be called to send a request. Defaults to true for GET requests and false for any other HTTP verbs.
  • See all the fetch options on MDN

Returns 

useFetch returns a tuple with the current state of the request and a function to send or re-send the request. The state is an object with the following fields:

• data: the response data, if the request was successful
• fetching: a boolean describing if the fetch request is currently in progress
• streaming: a boolean describing if the fetch request is currently streaming. This is only set when the option { stream: "string" } is set
• error: an error object if the request failed in any way

The second return value is a function for sending or resending the fetch request.

Request method 

By default, GET requests are sent as soon as the hook executes. GET requests can also be refreshed by calling the second return value to re-send the fetch request and fetch fresh data.

JavaScript
Copy
// GET request will be sent immediately, can be refreshed by calling `send()` again
const [{ data, fetching, error }, send] = useFetch("/some/route", { method: "GET" });
// ... sometime later
data; // => will be populated