Skip to main content

Settings

All apps have settings merchants need to configure to control your app's behavior. For React Router-based Shopify apps, this will be defined in a route file like app.settings.jsx.

The settings template organizes related options into logical groups that provide contextual help alongside form controls. It also leverages the Save Bar API to protect unsaved changes from being lost.

The settings pattern follows proven design guidelines that help your app feel native to the Shopify admin. See Built for Shopify requirements for more details on these guidelines.

Anchor to ExamplesExamples

Anchor to Configure a settings page with toggles and contextual helpConfigure a settings page with toggles and contextual help

Merchants need to configure app behavior; the settings template groups options and protects unsaved changes. This example configures a settings page for a Product Quality Auditor app with quality criteria toggles, weight controls, and notification preferences in the main column and contextual help in the aside. Add data-save-bar to your form element to enable the Save Bar API, which displays save/discard controls when the form has unsaved changes.

Preview

<form
data-save-bar
onSubmit={(event) => {
event.preventDefault();
const formData = new FormData(event.target);
const formEntries = Object.fromEntries(formData);
console.log("Form data", formEntries);
}}
onReset={(event) => {
console.log("Handle discarded changes if necessary");
}}
>
<s-page heading="Settings" inlineSize="small">
{/* === */}
{/* Store Information */}
{/* === */}
<s-section heading="Store Information">
<s-text-field
label="Store name"
name="store-name"
value="Puzzlify Store"
placeholder="Enter store name"
/>
<s-text-field
label="Business address"
name="business-address"
value="123 Main St, Anytown, USA"
placeholder="Enter business address"
/>
<s-text-field
label="Store phone"
name="store-phone"
value="+1 (555) 123-4567"
placeholder="Enter phone number"
/>
<s-choice-list label="Primary currency" name="currency">
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
<title>Pattern</title>
</head>
<body>
<!-- === -->
<!-- Settings page pattern -->
<!-- === -->
<form data-save-bar onSubmit="" onReset="">
<s-page heading="Settings" inlineSize="small">
<!-- === -->
<!-- Store Information -->
<!-- === -->
<s-section heading="Store Information">
<s-text-field
label="Store name"
name="store-name"
value="Puzzlify Store"
placeholder="Enter store name"
></s-text-field>
<s-text-field
label="Business address"
name="business-address"
value="123 Main St, Anytown, USA"
placeholder="Enter business address"
></s-text-field>
<s-text-field
label="Store phone"
name="store-phone"
value="+1 (555) 123-4567"
placeholder="Enter phone number"
></s-text-field>

Anchor to Confirm reset with Modal APIConfirm reset with Modal API

Use the Modal API to confirm destructive actions like resetting all settings to their default values.

Preview

<s-grid justifyItems="center" alignItems="center" minBlockSize="200px">
<s-box padding="small-100">
<s-grid
gridTemplateColumns="1fr auto"
alignItems="center"
gap="base"
>
<s-box>
<s-heading>Reset app settings</s-heading>
<s-paragraph color="subdued">
Reset all settings to their default values. This action cannot be undone.
</s-paragraph>
</s-box>
<s-button
tone="critical"
commandFor="reset-modal"
command="--show"
>
Reset
</s-button>
</s-grid>
</s-box>

<s-modal id="reset-modal" heading="Reset all settings?">
<s-stack direction="block" gap="base">
<s-text>
Are you sure you want to reset all settings to their default values? This will clear all your customizations and cannot be undone.
</s-text>
<s-banner tone="warning">
<s-text>
This will reset notification preferences, connected accounts, and all other configurations.
</s-text>
</s-banner>
</s-stack>
<s-button
slot="primary-action"
variant="primary"
tone="critical"
onClick={() => {
shopify.toast.show('Settings reset to defaults');
}}
>
Reset settings
</s-button>
<s-button
slot="secondary-actions"
commandFor="reset-modal"
command="--hide"
>
Cancel
</s-button>
</s-modal>
</s-grid>
<s-grid justifyItems="center" alignItems="center" minBlockSize="200px">
<s-box padding="small-100">
<s-grid
gridTemplateColumns="1fr auto"
alignItems="center"
gap="base"
>
<s-box>
<s-heading>Reset app settings</s-heading>
<s-paragraph color="subdued">
Reset all settings to their default values. This action cannot be undone.
</s-paragraph>
</s-box>
<s-button
tone="critical"
commandFor="reset-modal"
command="--show"
>Reset</s-button>
</s-grid>
</s-box>

<s-modal id="reset-modal" heading="Reset all settings?">
<s-stack direction="block" gap="base">
<s-text>
Are you sure you want to reset all settings to their default values? This will clear all your customizations and cannot be undone.
</s-text>
<s-banner tone="warning">
<s-text>
This will reset notification preferences, connected accounts, and all other configurations.
</s-text>
</s-banner>
</s-stack>
<s-button
slot="primary-action"
variant="primary"
tone="critical"
onClick="shopify.toast.show('Settings reset to defaults')"
>Reset settings</s-button>
<s-button
slot="secondary-actions"
commandFor="reset-modal"
command="--hide"
>Cancel</s-button>
</s-modal>
</s-grid>

Anchor to Show save feedback with Toast APIShow save feedback with Toast API

Use the Toast API to show feedback when settings are saved. Combine with the Save Bar API for a complete form experience.

<form
data-save-bar
onSubmit={(event) => {
event.preventDefault();
const formData = new FormData(event.target);
const formEntries = Object.fromEntries(formData);
console.log("Form data", formEntries);
shopify.toast.show('Settings saved successfully');
}}
onReset={(event) => {
console.log("Handle discarded changes if necessary");
}}
>
<s-section heading="Notifications">
<s-select
label="Notification frequency"
name="notification-frequency"
>
<s-option value="immediately" selected>Immediately</s-option>
<s-option value="hourly">Hourly digest</s-option>
<s-option value="daily">Daily digest</s-option>
</s-select>
<s-choice-list
label="Notification types"
name="notifications-type"
multiple
>
<s-choice value="new-order" selected>New order notifications</s-choice>
<s-choice value="low-stock">Low stock alerts</s-choice>
<s-choice value="customer-review">Customer review notifications</s-choice>
</s-choice-list>
</s-section>
</form>
<script>
function handleSubmit(event) {
event.preventDefault();
const formData = new FormData(event.target);
const formEntries = Object.fromEntries(formData);
console.log("Form data", formEntries);
shopify.toast.show('Settings saved successfully');
}
function handleReset(event) {
console.log("Handle discarded changes if necessary");
}
</script>
<form
data-save-bar
onSubmit="handleSubmit(event)"
onReset="handleReset(event)"
>
<s-section heading="Notifications">
<s-select
label="Notification frequency"
name="notification-frequency"
>
<s-option value="immediately" selected>Immediately</s-option>
<s-option value="hourly">Hourly digest</s-option>
<s-option value="daily">Daily digest</s-option>
</s-select>
<s-choice-list
label="Notification types"
name="notifications-type"
multiple
>
<s-choice value="new-order" selected>New order notifications</s-choice>
<s-choice value="low-stock">Low stock alerts</s-choice>
<s-choice value="customer-review">Customer review notifications</s-choice>
</s-choice-list>
</s-section>
</form>
Was this page helpful?