---
title: Save bar API
description: "The Save Bar API indicates that a form on the current page has unsaved information. You can implement save bar behavior in two ways: 1."
api_name: app-home
source_url:
  html: https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/save-bar-api
  md: https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/save-bar-api.md
---

# 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:

1. **Form attribute**: Add the `data-save-bar` attribute to a [`form` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form). The save bar displays automatically when there are unsaved changes. The [`submit`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event) event fires when the Save button is pressed, and the [`reset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/reset_event) event fires when the Discard button is pressed.

2. **Programmatic control**: Use `shopify.saveBar` methods (`show()`, `hide()`, `toggle()`, `leaveConfirmation()`) to control the save bar based on your application state.

### Use 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.

### Methods

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

* **hide**

  **(id: string) => Promise\<void>**

  Hides the save bar. Call this after the merchant saves or discards their changes.

* **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.

* **show**

  **(id: string) => Promise\<void>**

  Displays the save bar to indicate unsaved changes. Call this when you want to prompt the merchant to save.

* **toggle**

  **(id: string) => Promise\<void>**

  Toggles save bar visibility between shown and hidden states.

Examples

## Preview

![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.](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/images/templated-apis-screenshots/admin/apis/contextual-save-bar-D20oMpjo.png)

### 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

  ```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

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

  ##### Event listener

  ```html
  <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

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

  ##### Event listener

  ```html
  <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

  ```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

  ```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

  ```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

  ```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>
    );
  }
  ```

***