Forms

Most Create and Edit actions require the use of forms for data input. Good form design is important because these are likely the most frequent touchpoints that merchants have with your app.

Guidance

Anchor link to section titled "Guidance"

Many apps have complex forms, with many input fields. This can be overwhelming for merchants.

Ensure that your forms use proper spacing by using the Polaris Form layout component.

Follow this guidance to create organized forms that will be easy for merchants to understand.

Use progressive disclosure when form inputs or information changes depending on input values. This prevents merchants from becoming overwhelmed by very long forms.
A dedicated page with a single form to edit a single entity.
The Shopify admin uses individual pages for object definitions. For example, a single page is used for a single product definition, or a single page is used for a variant definition. Following this pattern can help focus merchant workflows and make your app look more like the Shopify admin.
A form with multiple sections, each with its own title. A form split into multiple cards, each with its own title.

Must Do

For more than five inputs, use sections with titles in one card or use multiple cards with headers.
A large form within a modal.

Do Not

Don’t place large forms inside max height, max width modals. Instead, create a new page in your embedded app to give merchants room to work with the form inputs.
The contextual save bar visible at the top of the page. The bar indicates that there are unsaved changes, and includes buttons to discard or save changes.

Tip

Form inputs can be saved using the App Bridge Contextual Save Bar API. Continuous data validation or auto-save for forms is incongruous with the standard Shopify admin save UX.
Form fields with error messages.
Refer to the Alerts page for guidance on how to show form errors to merchants.