Skip to main content

Save bar

Info

App Bridge isn't versioned with Polaris. App Bridge APIs and web components are identical in every App Home reference version.

Enable automatic save bar integration for HTML forms by adding the data-save-bar attribute to your form element. When form data changes, a save bar automatically appears, prompting users to save or discard their changes.

Alternatively, use the Save Bar API for programmatic control over the save bar behavior. Choose one approach or the other. Don't combine data-save-bar with programmatic methods on the same page.

To put a save bar in an <s-app-window>, add data-save-bar to a form inside the window. The save bar then opens and closes with the window. Don't use a <ui-save-bar> on the parent page and show it from inside the window: that bar belongs to the parent page, so it appears behind the window and merchants can't see or click Save or Discard. See Save bar in an iframe window.

Info

The save bar functionality requires the full App Bridge UI library to be loaded using a script tag.

  • Form change tracking: Automatically detect unsaved form changes and display a save bar using the data-save-bar attribute.
  • Save and discard: Provide merchants with clear save and discard actions when form data has been modified.
  • Discard confirmation: Add a confirmation dialog before discarding changes to prevent accidental data loss.
  • Form reset handling: Listen for form submit and reset events to handle save and discard actions.

Add these attributes to your <form> element to enable save bar integration.

Anchor to data-discard-confirmation
data-discard-confirmation
boolean

Shows a confirmation dialog when the discard button is clicked, requiring merchants to confirm before losing their changes. The dialog prevents accidental data loss by adding a second step before reset. Commonly used for forms with significant data entry, multi-step workflows, or when changes cannot be easily recreated.

Anchor to data-save-bar
data-save-bar
boolean

Enables automatic save bar integration. When present, the save bar appears whenever any form input value changes from its initial state. The save bar automatically hides when the form is submitted or reset. Commonly used for settings pages, product editors, or any form where merchants need visual feedback about unsaved changes.

Anchor to onreset
onreset
(event: Event) => void

Handler called when the form is reset via the save bar's discard button. Receives a standard Event that can be prevented with event.preventDefault() for custom discard logic. Commonly used for reverting form fields to their original values, clearing temporary state, or confirming discard actions programmatically.

Anchor to onsubmit
onsubmit
(event: SubmitEvent) => void

Handler called when the form is submitted via the save bar's save button. Receives a standard SubmitEvent that can be prevented with event.preventDefault() for custom async save logic. Commonly used for API calls to persist data, form validation before save, or showing success/error toasts after the operation completes.


Anchor to How the save bar tracks changesHow the save bar tracks changes

App Bridge compares each field in the form with the field's saved value. The saved value is the value that the field had before the merchant's first edit. After the form's submit event, the current values become the saved values. After the form's reset event, a text or number field returns to its saved value. A checkbox or a select can return to its default value instead, which can be a value from before the last submit event.

The save bar shows when a field that the merchant edited has a value that's different from its saved value. App Bridge checks the form again after an input or change event from a field, and after the form's submit or reset event. The browser fires input and change events when the merchant edits a field, but not when your code sets the field's value.

App Bridge ignores values that your code sets, so a value that your app renders doesn't show the save bar. The save bar also keeps its state after your code changes a value. For example, if your app saves default values from a dialog and then sets the fields to those values in code, then the save bar still shows Unsaved changes and still blocks navigation.

After your code changes form values, sync the save bar:

  • The values are now saved: For example, your app saved them outside of the save bar, or reloaded them from your server. Call the form's requestSubmit() method. The submit event makes the current values the saved values, and the save bar hides. Your submit event handlers also run, so save the values there, the same as when the merchant clicks Save. Refer to Sync the save bar after your code changes values.
  • The values are the saved values again: For example, your app sets its state back to the saved state. On each field that you changed, dispatch an input event that bubbles: field.dispatchEvent(new Event('input', {bubbles: true})). The save bar hides when every field has its saved value.

Don't call the form's reset() method to keep values that your code set. A reset sets each field back to its saved value or to its default value, so the values that your code set are lost.


Anchor to Form with automatic save barForm with automatic save bar

Add the data-save-bar attribute to a form to automatically show a save bar when form data changes.

Form with automatic save bar

Add the `data-save-bar` attribute to a form to automatically show a save bar when form data changes.

html

<form data-save-bar>
<s-text-field
label="Product Title"
name="title"
required
></s-text-field>

<s-text-area
label="Description"
name="description"
rows="4"
></s-text-area>

<s-text-field
label="Price"
name="price"
></s-text-field>
</form>

Anchor to Submit and reset handlersSubmit and reset handlers

Handle form submission and reset using standard HTML form events.

Submit and reset handlers

Handle form submission and reset using standard HTML form events.

html

<form
data-save-bar
onSubmit="console.log('submit');"
onReset="console.log('reset');"
>
<s-text-field label="Name" name="name"></s-text-field>
<s-button type="submit">Submit</s-button>
<s-button type="reset">Reset</s-button>
</form>

Anchor to Discard confirmationDiscard confirmation

Add data-discard-confirmation to show a confirmation dialog when the discard button is clicked, preventing accidental data loss.

Discard confirmation

Add `data-discard-confirmation` to show a confirmation dialog when the discard button is clicked, preventing accidental data loss.

html

<form data-save-bar data-discard-confirmation>
<s-text-field
label="Store Name"
name="storeName"
required
></s-text-field>

<s-text-area
label="Store Description"
name="description"
rows="4"
></s-text-area>

<s-checkbox
label="Enable notifications"
name="notifications"
></s-checkbox>
</form>

Anchor to Save bar in an iframe windowSave bar in an iframe window

Define a <ui-save-bar> on the parent page with a unique id, then call shopify.saveBar.show(id) from inside the iframe when changes are detected, and shopify.saveBar.hide(id) after save or discard. This bar belongs to the parent page, not the window, so it appears behind an open app window and merchants can't see or click Save or Discard. To give the window its own save bar, add data-save-bar to a form inside the window.

function ParentPage() {
const saveBarId = 'modal-save-bar';

const handleSave = async () => {
await fetch('/api/save', {method: 'POST'});
shopify.saveBar.hide(saveBarId);
};

const handleDiscard = () => {
shopify.saveBar.hide(saveBarId);
};

return (
<s-page heading="Settings">
<ui-save-bar id={saveBarId}>
<button variant="primary" onClick={handleSave}>Save</button>
<button onClick={handleDiscard}>Discard</button>
</ui-save-bar>
<s-app-window src="/settings" />
</s-page>
);
}
function SettingsPage() {
return (
<s-section heading="Configuration">
<s-text-field
label="Store name"
onInput={() => shopify.saveBar.show('modal-save-bar')}
/>
</s-section>
);
}

Anchor to Sync the save bar after your code changes valuesSync the save bar after your code changes values

Call the form's requestSubmit() method after your code sets values that are now saved. This example sets the default margin when the merchant clicks Reset to defaults, and then submits the form. The submit handler saves the value, and the save bar hides.

html

<form data-save-bar>
<s-number-field label="Margin" name="margin" value="20"></s-number-field>
</form>
<s-button id="reset-defaults">Reset to defaults</s-button>

<script>
const form = document.querySelector('form');

form.addEventListener('submit', async (event) => {
event.preventDefault();
await fetch('/api/settings', {method: 'POST', body: new FormData(form)});
shopify.toast.show('Settings saved');
});

document.querySelector('#reset-defaults').addEventListener('click', () => {
form.elements.margin.value = '15';
// The submit event saves the new value and makes it the saved value,
// so the save bar hides.
form.requestSubmit();
});
</script>

  • Always provide discard functionality: Allow merchants to revert changes by handling the discard action or using form reset.
  • Show loading states during save: Use the Loading API to indicate when an async save operation is in progress.
  • Use data-discard-confirmation for destructive forms: Add a confirmation dialog when discarding changes would result in significant data loss.
  • Keep a window's save bar inside the window: For <s-app-window src="..."> content, add data-save-bar to a form inside the window so the save bar opens and closes with it. A <ui-save-bar> on the parent page belongs to the parent page, so it appears behind the window. See Save bar in an iframe window.
  • Reset the form before your app navigates: Before a navigation that ends the edit, such as a redirect after a delete, call the form's reset() method. While the save bar shows, the admin's address bar doesn't follow your app's route changes. For more information, refer to Navigation while the save bar shows.

Was this page helpful?