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:
<AutoTablemodel={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:
<AutoTablemodel={api.widget}/>
Props
The AutoTable component accepts the following props:
Name
Type
Description
model
ModelFinder
Required. This is the data model you wish to show the records of. Ex: api.yourModelName
select?
FieldSelection
A list of fields and subfields to select. This will override the default selection. See the Select option docs
pageSize?
number
Page size of the paginated table. Defaults to 50
initialCursor?
string
A string cursor; useTable handles pagination, this prop is only needed if you want to set the cursor to a custom spot
initialDirection?
string
Pagination direction; either "forward" or "backward", defaults to "forward"
live?
boolean
Change the table in real time when a record is created/updated/deleted. Defaults to false
onClick?
(row) => void
Perform a custom action when a table row is clicked
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?
FilterObject
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
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?
boolean
Toggle whether rows are selectable. Defaults to true
emptyState?
React.React.ReactNode
What to render when there are no records to populate the table
lastColumnSticky?
boolean
Toggle whether the last column is always visible. Defaults to false
hasZebraStriping?
boolean
Add 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?
boolean
Condense the table, so that the user does not have to scroll horizontally. Defaults to false
searchable?
boolean
Toggle 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
<AutoFormaction={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
<AutoFormaction={api.widget.create}/>
Parameters
Name
Type
Description
action
ActionFunc
Required. Which action this form will run on submit
title
string | false
A 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?
DefaultValues
A 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.ReactNode
The label to use for the submit button at the bottom of the form
successContent?
React.ReactNode
What to show the user once the form has been submitted successfully
onSuccess?
(record) => void
Called when the form submission completes successfully on the backend
onFailure?
(error) => void
Called 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:
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.
Name
Type
Description
field
string
Required. API identifier of the field you wish to render as a file input.
value?
any
Value 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.
Name
Type
Description
field
string
Required. 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.
Name
Type
Description
field
string
Required. API identifier of the field you wish to render as a JSON input. The field must be of type json.
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.
Name
Type
Description
field
string
Required. 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.
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.
Name
Type
Description
field
string
Required. API identifier of the field you wish to render as a combobox. The field must be of type role list.
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
<AutoBelongsToInputfield="section"optionLabel={(record:{ id:string})=>`Custom label for ${record.id}`}/>
<AutoBelongsToInputfield="section"optionLabel={(record:{id: string })=>`Custom label for ${record.id}`}/>
Name
Type
Description
field
string
Required. API identifier of the field you wish to render as a text input. The field must be of type belongs to.
Type 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.
Name
Type
Description
field
string
Required. API identifier of the field you wish to render as a text input. The field must be of type belongs to.
Type 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.
Name
Type
Description
action
ActionFunc
Required. Which action will run when the form is submitted.
variables?
any
The variables to pass to the action when run. See the <AutoButton /> guide for examples on how to pass in variables.
onSuccess?
(result) => void
Callback 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) => void
Callback 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.
Name
Type
Description
children?
React.ReactNode
Children can be passed to <AutoSubmit /> to customize its label.
isSubmitting?
boolean
Loading 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.
Name
Type
Description
successfulBannerProps?
Polaris.BannerProps
What banner to render when the form is submitted successfully.
errorBannerProps?
Polaris.BannerProps
What banner to render when the form is submitted unsuccessfully.
The props list for Polaris.BannerProps can be found here.