@gadgetinc/react/auto 

The @gadgetinc/react/auto package powers Gadget autocomponents: beautiful auto-generated tables and forms pre-configured to read and write data using your Gadget app's auto-generated API.

The following is a comprehensive list of each autocomponent and its properties. Refer to the autocomponents guide for examples of how to use these components in your application.

The Gadget team is looking to create autocomponents from different design systems like MUI. Let the team know which design system we should add next on Discord.

<AutoTable /> 

The AutoTable component reads data from your database and renders each record as a row in the table. Pagination, search, and sorting are included in AutoTable components and are configurable with parameters.

// The only required prop is "model": this is the data model you wish to show the records of
// Use your Gadget API to pass in the model:
<AutoTable model={api.widget} />

// The only required prop is "model": this is the data model you wish to show the records of
// Use your Gadget API to pass in the model:
<AutoTable model={api.widget} />

Props 

The AutoTable component accepts the following props:

Props passed to the components in different design systems:

• Polaris: IndexTable
• Shadcn: N/A

<AutoForm /> 

<AutoForm /> renders a form that calls one of your app's backend API actions. You can use <AutoForm /> for model actions to create, update, or delete records. Global actions can also be called from <AutoForm />.

// The only required prop is "action": the action you wish to perform when the form is submitted
// Common actions are "create" & "update"
// These create/update a record based on the values entered in the form
<AutoForm action={api.widget.create} />

// The only required prop is "action": the action you wish to perform when the form is submitted
// Common actions are "create" & "update"
// These create/update a record based on the values entered in the form
<AutoForm action={api.widget.create} />

Props 

The AutoForm can be customized by adding children. Here's an example with the Polaris design system:

1import { AutoForm, AutoStringInput, AutoBooleanInput, AutoSubmit } from "@gadgetinc/react/auto/polaris";
2import { api } from "../api";
3
4export const MyCustomForm = () => {
5  return (
6    <>
7      <AutoForm action={api.customer.create}>
8        <h1>Subscribe to our newsletter!</h1>
9        <AutoStringInput field="email" />
10        <SubmitResultBanner />
11        <AutoSubmit />
12      </AutoForm>
13    </>
14  );
15};

1import { AutoForm, AutoStringInput, AutoBooleanInput, AutoSubmit } from "@gadgetinc/react/auto/polaris";
2import { api } from "../api";
3
4export const MyCustomForm = () => {
5  return (
6    <>
7      <AutoForm action={api.customer.create}>
8        <h1>Subscribe to our newsletter!</h1>
9        <AutoStringInput field="email" />
10        <SubmitResultBanner />
11        <AutoSubmit />
12      </AutoForm>
13    </>
14  );
15};

Adding custom children to an <AutoForm /> disables the title and submitLabel props and requires you to manually include the <AutoSubmit /> and <SubmitResultBanner /> components.

Custom selection and conditionally rendered inputs 

If you have an update action in an <AutoForm /> with custom child components, you may encounter a refetch for the existing record when the inputs appear conditionally. Consider a situation like this where you have a button that controls the appearance of some AutoInput components.

1// select prop to prevent refetching with conditionally rendered inputs
2const AutoFormWithCustomChildren = () => {
3  return (
4    <AutoForm
5      action={api.widget.update}
6      findBy="123"
7      select={
8        // The `select` prop overrides the default selection, which will not include the conditionally rendered inputs.
9        {
10          widget: {
11            name: true,
12            inventoryCount: true,
13            owner: {
14              // For relationship fields, select related model fields
15              id: true,
16              name: true,
17            },
18          },
19        }
20      }
21    >
22      <AutoInput field="name" />
23      <ConditionallyAppearingAutoInputs />
24      <AutoSubmit />
25    </AutoForm>
26  );
27};
28
29const ConditionallyAppearingAutoInputs = () => {
30  const [showMoreInputs, setShowMoreInputs] = useState(false);
31
32  return (
33    <>
34      <Button onClick={() => setShowMoreInputs(!showMoreInputs)}>{showMoreInputs ? "Hide" : "Show"} more inputs</Button>
35      {showMoreInputs && (
36        <>
37          {/* These fields are not included in the initial existing record selection by default. */}
38          {/* They will cause a refetch when rendered for the first time unless the `select` prop is used to includes these fields. */}
39          <AutoInput field="inventoryCount" />
40          <AutoInput field="owner" />
41        </>
42      )}
43    </>
44  );
45};

1// select prop to prevent refetching with conditionally rendered inputs
2const AutoFormWithCustomChildren = () => {
3  return (
4    <AutoForm
5      action={api.widget.update}
6      findBy="123"
7      select={
8        // The `select` prop overrides the default selection, which will not include the conditionally rendered inputs.
9        {
10          widget: {
11            name: true,
12            inventoryCount: true,
13            owner: {
14              // For relationship fields, select related model fields
15              id: true,
16              name: true,
17            },
18          },
19        }
20      }
21    >
22      <AutoInput field="name" />
23      <ConditionallyAppearingAutoInputs />
24      <AutoSubmit />
25    </AutoForm>
26  );
27};
28
29const ConditionallyAppearingAutoInputs = () => {
30  const [showMoreInputs, setShowMoreInputs] = useState(false);
31
32  return (
33    <>
34      <Button onClick={() => setShowMoreInputs(!showMoreInputs)}>{showMoreInputs ? "Hide" : "Show"} more inputs</Button>
35      {showMoreInputs && (
36        <>
37          {/* These fields are not included in the initial existing record selection by default. */}
38          {/* They will cause a refetch when rendered for the first time unless the `select` prop is used to includes these fields. */}
39          <AutoInput field="inventoryCount" />
40          <AutoInput field="owner" />
41        </>
42      )}
43    </>
44  );
45};

A refetch will occur when the AutoInput components with inventoryCount and owner get rendered for the first time. To prevent this refetch, you can use the select prop in <AutoForm /> to override the default selection behavior to include all field inputs that can be potentially rendered in the form.

<AutoInput /> 

This input detects the type of the field, and renders the correct input type. If the field is of type date / time, the AutoInput will return a date/time picker.

If you wish to customize the AutoInput further, use the input that corresponds to the type of the field.

<AutoHiddenInput /> 

The hidden input allows you to add to the form submission without rendering an input. An example would be including user preferences in a hidden input. When a user submits the form, their preferences are included in the form submission without any extra input from them.

<AutoBooleanInput /> 

Props passed to the components by different design systems:

• Polaris: Checkbox
• Shadcn: Checkbox

<AutoDateTimePicker /> 

Props passed to the components by different design systems:

• Polaris: Date picker
• Shadcn: Calendar

<AutoEncryptedStringInput /> 

A component that allows users to enter strings which they want to encrypt.

Props passed to the components by different design systems:

• Polaris: TextField
• Shadcn: Input

<AutoEnumInput /> 

A component that allows the user to select one or more options.

Props passed to the components by different design systems:

• Polaris: ComboBox
• Shadcn: N/A

<AutoFileInput /> 

A file input box.

Props passed to the components by different design systems:

• Polaris: DropZone
• Shadcn: N/A

<AutoJSONInput /> 

An input with built-in JSON validation.

Props passed to the components by different design systems:

• Polaris: TextField minus onChange
• Shadcn: Input

<AutoNumberInput /> 

A text field, with number validations.

Props passed to the components by different design systems:

• Polaris: TextField
• Shadcn: Input

<AutoPasswordInput /> 

A text field, with special validations for passwords. Upon submission, inputs are encrypted and stored in a shared Postgres database hosted by Gadget.

Props passed to the components by different design systems:

• Polaris: TextField
• Shadcn: Input

<AutoRolesInput /> 

A Gadget app has one global list of roles that governs permissions across the application. This input allows users to select the roles that have been defined. Learn more about roles and access control here.

Props passed to the components by different design systems:

• Polaris: TextField
• Shadcn: Input

<AutoEmailInput /> 

A text field that has validations so it only accepts strings that have a valid email format.

Props passed to the components by different design systems:

• Polaris: TextField
• Shadcn: Input

<AutoStringInput /> 

A text field that accepts any string.

Props passed to the components by different design systems:

• Polaris: TextField
• Shadcn: Input

<AutoUrlInput /> 

A text input with builtin validation for URLs.

Props passed to the components by different design systems:

• Polaris: TextField
• Shadcn: Input

<AutoRichTextInput /> 

A text input for rich text fields, powered by MDXEditor.

There are currently no props passed to the MDX editor by different design systems.

<AutoButton /> 

<AutoButton /> renders a button that calls one of your app's backend API actions onClick. You can use <AutoButton /> for model actions to create, update, or delete records, or to call a global action.

Props passed to the components by different design systems:

• Polaris: Button
• Shadcn: Button

<AutoSubmit /> 

Submits the AutoForm onClick.

Props passed to the components by different design systems:

• Polaris: Button
• Shadcn: Button

<SubmitResultBanner /> 

The customizable banner users see when they submit your AutoForm.

Props passed to the components by different design systems:

• Polaris: Banner
• Shadcn:

The props list for Polaris.BannerProps can be found here.

Relationship inputs 

<AutoBelongsToInput /> 

The <AutoBelongsToInput /> component allows users to pick records on the related model to associate with this belongs to field.

If the Gadget backend has a field like this:

<AutoBelongsToInput /> will render it like this:

Each email is taken from a record in the customer table. The autocomponents system labelled the options with the customer's email. To render a custom label, use the optionLabel prop. This component requires the read and update permissions.

1<AutoForm action={api.purchase.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `customer` field on `purchase` model */}
4  <AutoBelongsToInput field="customer" optionLabel={(record: { id: string }) => `Customer ${record.id}`} />
5  <AutoSubmit />
6</AutoForm>

1<AutoForm action={api.purchase.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `customer` field on `purchase` model */}
4  <AutoBelongsToInput field="customer" optionLabel={(record: { id: string }) => `Customer ${record.id}`} />
5  <AutoSubmit />
6</AutoForm>

<AutoHasOneInput /> 

The <AutoHasOneInput /> component allows users to pick a single record from the related model. The relationship is defined on by the belongs to field on the child model, and the 1:1 mapping between records will be maintained.

1<AutoForm action={api.car.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `engine` field on `car` model */}
4  <AutoHasOneInput field="engine" label="Engine" />
5  <AutoSubmit />
6</AutoForm>

1<AutoForm action={api.car.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `engine` field on `car` model */}
4  <AutoHasOneInput field="engine" label="Engine" />
5  <AutoSubmit />
6</AutoForm>

The has one relationship will be updated by changing the ID value stored in the belongs to field on the related model. The related model will require the update permission.

Use the recordFilter prop to help avoid unlinking a relationship between already linked parent and child records.

<AutoHasManyInput /> 

The <AutoHasManyInput /> component allows users to pick records from the related model to associate with the current record.

A multi-select combobox is used. If AutoForm is associated the some model customer, each purchase that is selected belongs to the customer model.

The purchase model has a belongs to relationship with the customer model. The purchase model needs the read permission to use this input.

1<AutoForm action={api.course.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `name` field on `course` model */}
4  <AutoInput field="name" label="Name" />
5  {/* `textbooks` field on `course` model */}
6  <AutoHasManyInput field="textbooks" label="Textbooks" />
7  <AutoSubmit />
8</AutoForm>

1<AutoForm action={api.course.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `name` field on `course` model */}
4  <AutoInput field="name" label="Name" />
5  {/* `textbooks` field on `course` model */}
6  <AutoHasManyInput field="textbooks" label="Textbooks" />
7  <AutoSubmit />
8</AutoForm>

Note that selecting a new parent for a child record will unlink the child from the previous parent. Use the recordFilter prop to help avoid unlinking a relationship between already linked parent and child records by filtering out any records with a parent relationship.

<AutoHasManyThroughInput /> 

The <AutoHasManyThroughInput /> component allows users to select records from the related model and make associations through creating and removing records in the join model. The join model has a belongs to field associated with the current model's has many through field, and another belongs to field associated with the related model's has many through field. A relationship between the current model and the related model is defined by the existence of a record in the join model that is associated with the corresponding current model record and related model record.

1<AutoForm action={api.course.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `name` field on `course` model */}
4  <AutoInput field="name" />
5  {/* `students` field on `course` model - `course` hasMany `students` through `registration` */}
6  <AutoHasManyThroughInput field="students" label="Students" />
7  <AutoSubmit />
8</AutoForm>

1<AutoForm action={api.course.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `name` field on `course` model */}
4  <AutoInput field="name" />
5  {/* `students` field on `course` model - `course` hasMany `students` through `registration` */}
6  <AutoHasManyThroughInput field="students" label="Students" />
7  <AutoSubmit />
8</AutoForm>

This input requires that you add a few different permissions to the access control page. The model with the hasManyThrough relationship and the join model must have all permissions enabled in order to use this input. The sibling model must have the read permission enabled.

Note that the recordFilter prop only applies to sibling model selection dropdown in the case of the has many through relationship.

Relationship forms 

Relationship forms are AutoForm input components that allow users to create, update, and delete related records through the relationship fields of an action's model.

<AutoBelongsToForm /> 

The <AutoBelongsToForm /> component allows users to select, create, or edit a record associated with the current record through a belongs to field.

1<AutoForm action={api.productVariant.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `name` field on `productVariant` model */}
4  <AutoInput field="name" />
5  {/* `product` field on `productVariant` model - belongsTo field */}
6  <AutoBelongsToForm field="product">
7    {/* `name` field on `product` model */}
8    <AutoInput field="name" />
9  </AutoBelongsToForm>
10  <AutoSubmit />
11</AutoForm>

1<AutoForm action={api.productVariant.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `name` field on `productVariant` model */}
4  <AutoInput field="name" />
5  {/* `product` field on `productVariant` model - belongsTo field */}
6  <AutoBelongsToForm field="product">
7    {/* `name` field on `product` model */}
8    <AutoInput field="name" />
9  </AutoBelongsToForm>
10  <AutoSubmit />
11</AutoForm>

Using a <AutoBelongsToForm/> component requires the read, create, and update permissions on related model.

<AutoHasOneForm /> 

The <AutoHasOneForm /> component allows users to create, update, or unlink a record in the related model through a has one relationship. The relationship is defined on by the belongs to field on the related child model, and the 1:1 mapping between records will be maintained.

Unlinking the related record in a has one relationship is done by updating the related record's ID value in the corresponding belongs to field to be null. To use the <AutoHasOneForm /> component, the related model must have the read, create, and update permissions.

1<AutoForm action={api.car.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `engine` field on `car` model */}
4  <AutoHasOneForm field="engine">
5    {/* `horsepower` field on `engine` model */}
6    <AutoInput field="horsepower" />
7  </AutoHasOneForm>
8  <AutoSubmit />
9</AutoForm>

1<AutoForm action={api.car.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `engine` field on `car` model */}
4  <AutoHasOneForm field="engine">
5    {/* `horsepower` field on `engine` model */}
6    <AutoInput field="horsepower" />
7  </AutoHasOneForm>
8  <AutoSubmit />
9</AutoForm>

<AutoHasManyForm /> 

The <AutoHasManyForm /> component allows users to create, update, and delete related child records through a has many relationship field. When child records are unlinked in the <AutoHasManyForm /> component, they are deleted.

1<AutoForm action={api.course.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `name` field on `course` model */}
4  <AutoInput field="name" label="Name" />
5  {/* `textbooks` field on `course` model */}
6  <AutoHasManyForm field="textbooks">
7    {/* `title` field on the `textbook` model */}
8    <AutoInput field="title" label="Title" />
9  </AutoHasManyForm>
10  <AutoSubmit />
11</AutoForm>

1<AutoForm action={api.course.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `name` field on `course` model */}
4  <AutoInput field="name" label="Name" />
5  {/* `textbooks` field on `course` model */}
6  <AutoHasManyForm field="textbooks">
7    {/* `title` field on the `textbook` model */}
8    <AutoInput field="title" label="Title" />
9  </AutoHasManyForm>
10  <AutoSubmit />
11</AutoForm>

The <AutoHasManyForm /> component requires the read, create, update and delete permissions to the related model.

<AutoHasManyThroughForm /> 

The <AutoHasManyThroughForm /> component allows users to create, update, and delete associations with the sibling model through the join model. Associations between the current model and the sibling model are defined by the two belongs to fields on the join model that point to the current model and the sibling model.

1<AutoForm action={api.course.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `name` field on `course` model */}
4  <AutoInput field="name" />
5  {/* `students` field on `course` model - `course` hasMany `students` through `registration` */}
6  <AutoHasManyThroughForm field="students">
7    {/* Join model field inputs */}
8    <AutoHasManyThroughJoinModelForm>
9      <AutoInput
10        // `isTuitionPaid` field on `registration` model
11        field="isTuitionPaid"
12      />
13    </AutoHasManyThroughJoinModelForm>
14
15    {/* Sibling model field inputs */}
16    <AutoInput
17      // `firstName` field on `student` model
18      field="firstName"
19    />
20  </AutoHasManyThroughForm>
21  <AutoSubmit />
22</AutoForm>

1<AutoForm action={api.course.update} findBy="1">
2  <SubmitResultBanner />
3  {/* `name` field on `course` model */}
4  <AutoInput field="name" />
5  {/* `students` field on `course` model - `course` hasMany `students` through `registration` */}
6  <AutoHasManyThroughForm field="students">
7    {/* Join model field inputs */}
8    <AutoHasManyThroughJoinModelForm>
9      <AutoInput
10        // `isTuitionPaid` field on `registration` model
11        field="isTuitionPaid"
12      />
13    </AutoHasManyThroughJoinModelForm>
14
15    {/* Sibling model field inputs */}
16    <AutoInput
17      // `firstName` field on `student` model
18      field="firstName"
19    />
20  </AutoHasManyThroughForm>
21  <AutoSubmit />
22</AutoForm>

By default, AutoForm inputs within a <AutoHasManyThroughForm> will be associated with fields on the sibling model. To associate inputs with fields on the join model, wrap your AutoForm inputs with the <AutoHasManyThroughJoinModelForm /> component.

The <AutoHasManyThroughForm /> component requires the read, create, update, and delete permissions to the join model, and the read and update permissions to the sibling model.

Types