Save bar
App Bridge isn't versioned with Polaris. App Bridge APIs and web components are identical in every App Home reference version.
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.
The save bar functionality requires the full App Bridge UI library to be loaded using a script tag.
The save bar functionality requires the full App Bridge UI library to be loaded using a script tag.
Anchor to Use casesUse cases
- Form change tracking: Automatically detect unsaved form changes and display a save bar using the
data-save-barattribute. - 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.
Anchor to AttributesAttributes
Add these attributes to your <form> element to enable save bar integration.
- Anchor to data-discard-confirmationdata-discard-confirmationdata-discard-confirmationbooleanboolean
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-bardata-save-bardata-save-barbooleanboolean
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 onresetonresetonreset(event: Event) => void(event: Event) => void
Handler called when the form is reset via the save bar's discard button. Receives a standard
Eventthat can be prevented withfor custom discard logic. Commonly used for reverting form fields to their original values, clearing temporary state, or confirming discard actions programmatically.- Anchor to onsubmitonsubmitonsubmit(event: SubmitEvent) => void(event: SubmitEvent) => void
Handler called when the form is submitted via the save bar's save button. Receives a standard
that can be prevented withfor 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. Thesubmitevent makes the current values the saved values, and the save bar hides. Yoursubmitevent 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
inputevent 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 ExamplesExamples
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

html
Anchor to Submit and reset handlersSubmit and reset handlers
Handle form submission and reset using standard HTML form events.
Submit and reset handlers

html
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

html
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.
Parent page
// @validate-ignore: ButtonHTMLAttributes<HTMLButtonElement>
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>
);
}/settings route
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
Anchor to Best practicesBest practices
- 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-confirmationfor 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, adddata-save-barto 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.