Save bar API

The Save Bar API indicates that a form on the current page has unsaved information. You can implement save bar behavior in two ways:

Form attribute: Add the data-save-bar attribute to a form element. The save bar displays automatically when there are unsaved changes. The submit event fires when the Save button is pressed, and the reset event fires when the Discard button is pressed.
Programmatic control: Use shopify.saveBar methods (show(), hide(), toggle(), leaveConfirmation()) to control the save bar based on your application state.

Anchor to Use casesUse cases

Form management: Automatically detect and manage unsaved form changes with save and discard actions.
Data protection: Prevent accidental data loss by prompting users when leaving a page with unsaved changes.
Programmatic control: Show, hide, and toggle the save bar programmatically for custom form workflows.
Form integration: Integrate with HTML form elements using the data-save-bar attribute for automatic change tracking.

Anchor to MethodsMethods

The saveBar object provides methods to programmatically control save bar visibility.

Anchor to hide hide (id: string) => Promise<void>: Hides the save bar. Call this after the merchant saves or discards their changes.
Anchor to leaveConfirmation leaveConfirmation () => Promise<void>: Prompts the merchant to confirm before leaving the page when there are unsaved changes. The promise resolves when the merchant confirms or when no save bar is visible. Use this before programmatic navigation (for example, using window.location or custom routing) to prevent accidental data loss.
Anchor to show show (id: string) => Promise<void>: Displays the save bar to indicate unsaved changes. Call this when you want to prompt the merchant to save.
Anchor to toggle toggle (id: string) => Promise<void>: Toggles save bar visibility between shown and hidden states.

Examples

html

<form

data-save-bar

onsubmit="console.log('submit', new FormData(event.target)); event.preventDefault();"

<label>

Name:

</label>

</form>

Preview

Examples

Description

Display a save bar. This example adds the `data-save-bar` attribute to a form element. When the form has unsaved changes, the save bar appears automatically.

html

<form
  data-save-bar
  onsubmit="console.log('submit', new FormData(event.target)); event.preventDefault();"
>
  <label>
    Name:
    <input name="username" />
  </label>
</form>

Description

Handle discard events. This example subscribes to the [`reset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/reset_event) event to run custom logic when the merchant clicks the Discard button.

Event handler property

<form
  data-save-bar
  onreset="console.log('discarding')"
>
  <label>
    Name:
    <input name="username" />
  </label>
</form>

Event listener

<form data-save-bar>
  <label>
    Name:
    <input name="username" />
  </label>
</form>

<script>
  const form = document.querySelector('form');
  form.addEventListener('reset', (e) => {
    console.log('discarding');
  });
</script>

Description

Handle save events. This example subscribes to the [`submit`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event) event to run custom logic when the merchant clicks the Save button.

Event handler property

<form
  data-save-bar
  onsubmit="console.log('submitting');"
>
  <label>
    Name:
    <input name="username" />
  </label>
</form>

Event listener

<form data-save-bar>
  <label>
    Name:
    <input name="username" />
  </label>
</form>

<script>
  const form = document.querySelector('form');
  form.addEventListener('submit', (e) => {
    console.log('submitting');
  });
</script>

Description

Show discard confirmation. This example adds the `data-discard-confirmation` attribute to show a confirmation modal when the merchant clicks the Discard button, preventing accidental data loss.

html

<form
  data-save-bar
  data-discard-confirmation
  onsubmit="console.log('submit', new FormData(event.target)); event.preventDefault();"
>
  <label>
    Name:
    <input name="username" />
  </label>
</form>

Description

Control save bar programmatically. This example uses `saveBar.show()` and `saveBar.hide()` to manage the save bar based on form state changes.

tsx

function SaveBarExample() {
  const saveBar = shopify.saveBar;
  const [hasUnsavedChanges, setHasUnsavedChanges] = React.useState(false);

  const handleFieldInput = () => {
    if (!hasUnsavedChanges) {
      setHasUnsavedChanges(true);
      saveBar.show();
    }
  };

  const handleDiscard = () => {
    setHasUnsavedChanges(false);
    saveBar.hide();
  };

  const handleSave = async () => {
    // Save to your backend
    setHasUnsavedChanges(false);
    saveBar.hide();
  };

  return (
    <s-page heading="Settings">
      <s-section heading="Configuration">
        <s-text-field
          label="Store name"
          onInput={handleFieldInput}
        />
      </s-section>
    </s-page>
  );
}

Description

Toggle save bar. This example uses `saveBar.toggle()` to switch the save bar between shown and hidden states.

tsx

function ToggleExample() {
  const saveBar = shopify.saveBar;

  const handleToggle = () => {
    saveBar.toggle();
  };

  return (
    <s-page heading="Settings">
      <s-section heading="Controls">
        <s-button onClick={handleToggle}>
          Toggle save bar
        </s-button>
      </s-section>
    </s-page>
  );
}

Description

Leave confirmation. This example uses `saveBar.leaveConfirmation()` to prompt the merchant before programmatic navigation when there are unsaved changes.

tsx

function LeaveConfirmationExample() {
  const saveBar = shopify.saveBar;
  const [hasUnsavedChanges, setHasUnsavedChanges] = React.useState(false);

  const handleFieldInput = () => {
    if (!hasUnsavedChanges) {
      setHasUnsavedChanges(true);
      saveBar.show();
    }
  };

  const handleCustomNavigation = async () => {
    // Call leaveConfirmation before programmatic navigation
    await saveBar.leaveConfirmation();
    // Navigation proceeds after merchant confirms or if no unsaved changes
    window.location.href = '/other-page';
  };

  return (
    <s-page heading="Settings">
      <s-section heading="Configuration">
        <s-text-field
          label="Store name"
          onInput={handleFieldInput}
        />
        <s-button onClick={handleCustomNavigation}>
          Go to other page
        </s-button>
      </s-section>
    </s-page>
  );
}

Was this page helpful?