@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.

Polaris 

Autocomponents are rendered using components from Shopify's Polaris design system.

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.

React
// 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:

NameTypeDescription
modelModelFinderRequired. This is the data model you wish to show the records of. Ex: api.yourModelName
select?FieldSelectionA list of fields and subfields to select. This will override the default selection. See the Select option docs
pageSize?numberPage size of the paginated table. Defaults to 50
initialCursor?stringA string cursor; useTable handles pagination, this prop is only needed if you want to set the cursor to a custom spot
initialDirection?stringPagination direction; either "forward" or "backward", defaults to "forward"
live?booleanChange the table in real time when a record is created/updated/deleted. Defaults to false
onClick?(row) => voidPerform a custom action when a table row is clicked
columns?string[] | CellDetailColumn[] | CustomCellColumn[]Columns to include in the table. Fields are passed as an array of strings by API identifiers. For relationships, you can choose which field of the related model to render using dot notation such as shopifyProduct.sku. HasMany relationships require a fully qualified GraphQL path, such as shopifyProduct.edges.node.sku. You can also pass a detailed column with a custom header, in this form: { header: string, field: string }, or a custom cell column: { header: string, render: (GadgetRecord<any>) => React.ReactNode }
excludeColumns?string[]A list of API identifiers for columns to exclude from the table
initialSort?{ [key: string]: "Ascending" | "Descending" }See the Sorting section in your application's API documentation for more info
filter?FilterObjectFilters 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
actions?(string | ActionCallback)[]List of actions that AutoTable can execute on the records it renders. This prop is a list of action API identifiers in string form or action callback objects which can have custom labels, be promoted buttons, or run a JavaScript function, where the ActionCallback type is in the form: {label: string, promoted?: true, action: string | ((records: GadgetRecord<any>[]) => any)}
excludeActions?string[]Actions to exclude from the AutoTable
selectable?booleanToggle whether rows are selectable. Defaults to true
emptyState?React.React.ReactNodeWhat to render when there are no records to populate the table
lastColumnSticky?booleanToggle whether the last column is always visible. Defaults to false
hasZebraStriping?booleanAdd zebra striping to table rows. Defaults to false
resourceName?{ singular: string; plural: string }The name of the resource that is populating the table. For example, if each row corresponds to a customer, resourceName would be { singular: "customer"; plural: "customers" } this allows Polaris to populate the accessibility labels
condensed?booleanCondense the table, so that the user does not have to scroll horizontally. Defaults to false
searchable?booleanToggle whether the search bar is visible. Defaults to true

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

React
// 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} />
Parameters 
NameTypeDescription
actionActionFuncRequired. Which action this form will run on submit
titlestring | falseA custom form title, replacing the auto-generated title. Use false to hide the title
findBy?string | { [key: string]: any }Details for automatically finding a record to seed the form values. When passed as a string, will look up a record with that id. When passed an object, will call a findBy<Field> function on the api object to retrieve a record by that field. The field must have a uniqueness validation to function.
record?GadgetRecord<any>A record for this form to act on
include?string[]An allowlist of fields to render within the form. Only these fields will be rendered as inputs
exclude?string[]A denylist of fields to render within the form. Every field except these fields will be rendered as inputs
defaultValues?DefaultValuesA set of field values to pre-populate the form with on load. Only applies to create action forms. Must pass in fully-qualified path including the model name, for example: defaultValues={ { widget: { name: "foobar" } } }
submitLabel?React.ReactNodeThe label to use for the submit button at the bottom of the form
successContent?React.ReactNodeWhat to show the user once the form has been submitted successfully
onSuccess?(record) => voidCalled when the form submission completes successfully on the backend
onFailure?(error) => voidCalled when the form submission errors before sending, during the API call, or if the API call returns an error

The AutoForm can be customized by adding children. Here's an example:

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

<AutoBooleanInput /> 

Renders a Polaris checkbox.

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a checkbox. The field must be of type boolean.
control?Control<any>Control object from the React Hook Form library.

The <AutoBooleanInput /> takes the same props as the Polaris checkbox. The Polaris props list can be found here.

<AutoDateTimePicker /> 

Renders a Polaris themed date-time picker.

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a checkbox. The field must be of type date / time.
id?stringID for form input.
value?DatePreset value of the input. If this is set, it can only change if the callback function from onChange set value to a new date.
onChange?(value: Date) => voidA function that is triggered when the user changes the date or time. The new JS Date object is included as a param.
error?stringError message to display.
includeTime?booleanInclude the time picker. Defaults to whatever was specified on the Gadget backend for your specific field.
hideTimePopover?booleanHide the popover that shows the currently selected time. Defaults to false.
datePickerProps?DatePickerPropsFull props list can be found in the Polaris Date Picker docs.
timePickerProps?TimePickerPropsThe time picker takes the same props as a Polaris text field.

The DatePickerProps and TimePickerProps are passed in as objects.

custom input props
React
<DateTimePicker field="testDate" datePickerProps={{ weekStartsOn: 1 }} timePickerProps={{ placeholder: "Local time" }} />
<DateTimePicker field="testDate" datePickerProps={{ weekStartsOn: 1 }} timePickerProps={{ placeholder: "Local time" }} />

<AutoEncryptedStringInput /> 

A Polaris text field that allows users to enter strings which they want to encrypt.

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a checkbox. The field must be of type encrypted string.
control?Control<any>Control object from the React Hook Form library.

The <AutoEncryptedStringInput /> takes the same props as the Polaris text field. The Polaris props list can be found here.

<AutoEnumInput /> 

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

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a checkbox. The field must be of type enum.
control?Control<any>Control object from the React Hook Form library.

The <AutoEnumInput /> takes the same props as the Polaris combobox. The Polaris props list can be found here.

<AutoFileInput /> 

A Polaris file input box.

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a file input. The field must be of type file.
control?Control<any>Control object from the React Hook Form library.

The <AutoFileInput /> takes the same props as the Polaris drop zone. The Polaris props list can be found here.

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

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a file input.
value?anyValue of the hidden input. Users cannot change this directly.

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

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render.

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

<AutoJSONInput /> 

An input with built-in JSON validation.

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a JSON input. The field must be of type json.
control?Control<any>Control object from the React Hook Form library.

The <AutoJSONInput /> takes the same props as the Polaris text field, minus the onChange prop. The Polaris props list can be found here.

<AutoNumberInput /> 

A text field, with number validations.

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a number input. The field must be of type number.
control?Control<any>Control object from the React Hook Form library.

The <AutoNumberInput /> takes the same props as the Polaris text field. The Polaris props list can be found here.

<AutoPasswordInput /> 

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

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a password input. Each character will be rendered as a dot by default. The field must be of type password.
control?Control<any>Control object from the React Hook Form library.

The <AutoPasswordInput /> takes the same props as the Polaris text field. The Polaris props list can be found here.

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

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a combobox. The field must be of type role list.
control?Control<any>Control object from the React Hook Form library.
value?stringDefault value of the input.

The <AutoRolesInput /> takes the same props as the Polaris text field. The Polaris props list can be found here.

<AutoEmailInput /> 

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

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a text input. The field must be of type email.
control?Control<any>Control object from the React Hook Form library.

The <AutoEmailInput /> takes the same props as the Polaris text field. The Polaris props list can be found here.

<AutoStringInput /> 

A text field that accepts any string.

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a text input. The field must be of type string.
control?Control<any>Control object from the React Hook Form library.

The <AutoStringInput /> takes the same props as the Polaris text field. The Polaris props list can be found here.

<AutoUrlInput /> 

A text input with builtin validation for URLs.

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a text input. The field must be of type url.
control?Control<any>Control object from the React Hook Form library.

The <AutoUrlInput /> takes the same props as the Polaris text field. The Polaris props list can be found here.

<AutoRichTextInput /> 

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

NOTE: The "@mdxeditor/editor": "^3.8.0", dependency must be in your project's package.json file to use this component.

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a text input. The field must be of type rich text.
label?stringA label for the rich text input.
control?Control<any>Control object from the React Hook Form library.

<AutoBelongsToInput /> 

The <AutoBelongsToInput /> component allows users to pick from the records that have a belongs to relationship with the record the form is associated with.

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.

custom option label
React
<AutoBelongsToInput field="section" optionLabel={(record: { id: string }) => `Custom label for ${record.id}`} />
<AutoBelongsToInput field="section" optionLabel={(record: { id: string }) => `Custom label for ${record.id}`} />
NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a text input. The field must be of type belongs to.
control?Control<any>Control object from the React Hook Form library.
optionLabel?string | (record: Record<string, any>) => React.ReactNodeType for the option label when displaying a list of records from a related model.

<AutoHasManyInput /> 

The <AutoHasManyInput /> component allows users to pick from the records that have a has many relationship with the record the form is associated with.

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

NameTypeDescription
fieldstringRequired. API identifier of the field you wish to render as a text input. The field must be of type belongs to.
control?Control<any>Control object from the React Hook Form library.
optionLabel?string | (record: Record<string, any>) => React.ReactNodeType for the option label when displaying a list of records from a related model.

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

NameTypeDescription
actionActionFuncRequired. Which action will run when the form is submitted.
variables?anyThe variables to pass to the action when run. See the <AutoButton /> guide for examples on how to pass in variables.
onSuccess?(result) => voidCallback function to run when the button succeeded at running the action. Overrides the default behavior of rendering a message to the user to display success.
onError?(result) => voidCallback function to run when the button failed at running the action with an error. Overrides the default behavior of rendering a message to the user to display the error.

The <AutoButton /> takes the same props as the Polaris button component. The Polaris props list can be found here.

<AutoSubmit /> 

Submits the AutoForm onClick.

NameTypeDescription
children?React.ReactNodeChildren can be passed to <AutoSubmit /> to customize its label.
isSubmitting?booleanLoading state of the submit button. The button will render a spinner while isSubmitting is true.

<SubmitResultBanner /> 

The customizable banner users see when they submit your AutoForm.

NameTypeDescription
successfulBannerProps?Polaris.BannerPropsWhat banner to render when the form is submitted successfully.
errorBannerProps?Polaris.BannerPropsWhat banner to render when the form is submitted unsuccessfully.

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

Was this page helpful?