Contextual Save Bar

Note

This is a legacy API. Use the latest version of Contextual Save Bar instead.

Display the contextual save bar to indicate that a form on the current page contains unsaved information, or when the users is in the process of creating a new object, such as a product or customer. The contextual save bar provides save and discard buttons to a user.

A close-up image of a Shopify admin contextual save bar. The contextual save bar displays the message: Unsaved changes. It features two buttons: a white button with the label Discard, and a green button with the label Save.

The following are ways to use the contextual save bar:

Plain JavaScript
React hook
React component

Anchor to Plain JavaScriptPlain JavaScript

Anchor to Example codeExample code

Import the createApp function from @shopify/app-bridge and the ContextualSaveBar from @shopify/app-bridge/actions. Then use the createApp function to create an app.

Note

In the following example, config is a valid App Bridge configuration object. Learn more about configuring App Bridge.

import createApp from '@shopify/app-bridge';

import {ContextualSaveBar} from '@shopify/app-bridge/actions';

const app = createApp(config);

Anchor to Create and showCreate and show

Create a contextual save bar instance with some initial options. Then dispatch a SHOW action to display it on the page.

const contextualSaveBar = ContextualSaveBar.create(app, {

saveAction: {

disabled: false,

loading: false,

discardAction: {

disabled: false,

loading: false,

});

contextualSaveBar.dispatch(ContextualSaveBar.Action.SHOW);

Note

Navigation actions (Redirect and History) on Shopify Admin are also blocked while the contextual save bar is visible. If your app contains a title bar, you will not be able to make any updates to the title bar buttons while a contextual save bar is being shown. In addition, all title bar buttons will be disabled automatically while the contextual save bar is displayed. The disabled state of buttons inside the title bar are automatically reset to their previous states when the contextual save bar is hidden. To learn more about the title bar, see Title Bar action.

Anchor to Update optionsUpdate options

You can modify the options at any time using the set method. If the contextual save bar is visible, the UI will update immediately.

contextualSaveBar.set({discardAction: {loading: true}});

Anchor to HideHide

Dispatch a HIDE action when you want to hide the contextual save bar.

contextualSaveBar.dispatch(ContextualSaveBar.Action.HIDE);

Anchor to Subscribe to Discard and SaveSubscribe to Discard and Save

Subscribe to the contextual save bar actions (ContextualSaveBar.Action.DISCARD and ContextualSaveBar.Action.SAVE) in order to do something when a user clicks the Save or Discard button. The subscribe method returns a function that you can call to unsubscribe from the action.

To hide the contextual save bar, dispatch a ContextualSaveBar.Action.HIDE action in the subscribe callback.

const discardUnsubscribe = contextualSaveBar.subscribe(

ContextualSaveBar.Action.DISCARD,

function() {

// Hide the contextual save bar

contextualSaveBar.dispatch(ContextualSaveBar.Action.HIDE);

// Do something with the discard action

}

);

const saveUnsubscribe = contextualSaveBar.subscribe(

ContextualSaveBar.Action.SAVE,

function() {

// Optionally, show a loading spinner while the save action is in progress

contextualSaveBar.set({saveAction: {loading: true}});

await doSaveAction();

// Hide the contextual save bar

contextualSaveBar.dispatch(ContextualSaveBar.Action.HIDE);

}

);

// Unsubscribe

discardUnsubscribe();

saveUnsubscribe();

Anchor to UnsubscribeUnsubscribe

Call the unsubscribe method to remove all current subscriptions on the contextual save bar.

contextualSaveBar.subscribe(ContextualSaveBar.Action.DISCARD, function () {

// Do something with the discard action

// Hide the contextual save bar

contextualSaveBar.dispatch(ContextualSaveBar.Action.HIDE);

});

contextualSaveBar.subscribe(ContextualSaveBar.Action.SAVE, function () {

// Do something with the save action

// Hide the contextual save bar

contextualSaveBar.dispatch(ContextualSaveBar.Action.HIDE);

});

// Unsubscribe

contextualSaveBar.unsubscribe();

Note

Navigation actions (Redirect and History) on Shopify Admin are blocked while the contextual save bar is visible. To dispatch navigation actions, first dispatch ContextualSaveBar.Action.HIDE.

Anchor to ReactReact

Anchor to [object Object], hook`useContextualSaveBar` hook

useContextualSaveBar is a hook that accepts no arguments and returns an object with the following methods and objects:

show: ({fullWidth?: boolean; leaveConfirmationDisable?: boolean}) => void;
hide: () => void;
saveAction: { setOptions: (options: SaveActionOptions) => void };
discardAction: { setOptions: (options: DiscardActionOptions) => void };

Anchor to Example CodeExample Code

Note

When using the App Bridge React library, you need to wrap all of your App Bridge React code inside of a single App Bridge Provider.

import {Provider, useContextualSaveBar} from '@shopify/app-bridge-react';

function MyApp {

// Setup appBridgeConfig...

const {show, hide, saveAction, discardAction} = useContextualSaveBar();

saveAction.setOptions({

disabled: false,

loading: false,

onAction: () => console.log('On save action')

});

discardAction.setOptions({

disabled: false,

loading: false,

onAction: () => console.log('On discard action')

});

return (

<Button onClick={() => {

show({fullWidth: true, leaveConfirmationDisable: true});

}}>Show ContextualSaveBar</Button>

<Button onClick={() => {

hide();

}}>Hide ContextualSaveBar</Button>

</Provider>

);

}

Anchor to APIAPI

The useContextualSaveBar hook does not accept any props. The following are the APIs for the methods and objects that the hook returns:

show

Name	Type	Description	Required
fullWidth	`boolean`	Whether the contextual save bar should fill the entire screen width	No
leaveConfirmationDisable	`boolean`	Whether to show a confirmation modal after the user navigates away from the page	No

hide

No arguments.

Anchor to saveAction.setOptionssaveAction.setOptions

Refer to SaveActionOptions.

Anchor to discardAction.setOptionsdiscardAction.setOptions

Refer to DiscardActionOptions.

Anchor to [object Object], component`ContextualSaveBar` component

ContextualSaveBar is a component that accepts props.

Anchor to Example CodeExample Code

Note

When using the App Bridge React library, you need to wrap all of your App Bridge React code inside of a single App Bridge Provider.

import {Provider, ContextualSaveBar} from '@shopify/app-bridge-react';

function MyApp {

// Setup appBridgeConfig...

const saveAction = {

disabled: false,

loading: false,

onAction: () => console.log('On save action')

}

const discardAction = {

disabled: false,

loading: false,

onAction: () => console.log('On discard action')

}

return (

<ContextualSaveBar

saveAction={saveAction}

discardAction={discardAction}

fullWidth

leaveConfirmationDisable

visible

</Provider>

);

}

Anchor to PropsProps

The ContextualSaveBar component accepts the following props:

Name	Type	Description	Required
saveAction	`SaveActionOptions`	Options to customize save behaviour	No
discardAction	`DiscardActionOptions`	Options to customize discard behaviour	No
fullWidth	`boolean`	Whether the contextual save bar should fill the entire screen width	No
leaveConfirmationDisable	`boolean`	Whether to show a confirmation modal after the user navigates away from the page	No
visible	`boolean`	Whether the contextual save bar appears on the screen	No

Anchor to Shared APIsShared APIs

Both the ContextualSaveBar component and the useContextualSaveBar hook use the following types:

Anchor to [object Object]`SaveActionOptions`

Name	Type	Description	Required
disabled	`boolean`	Whether the contextual save bar button is in a disabled state	No
loading	`boolean`	Whether the contextual save bar button is in a loading state	No
onAction	`() => void`	A callback fired when the user presses the save button	No

Anchor to [object Object]`DiscardActionOptions`

Name	Type	Description	Required
disabled	`boolean`	Whether the contextual discard bar button is in a disabled state	No
loading	`boolean`	Whether the contextual discard bar button is in a loading state	No
onAction	`() => void`	A callback fired when the user presses the discard button	No
discardConfirmationModal	`boolean`	~~Whether to show a confirmation modal after the user clicks the Discard button of the contextual save bar~~ This property no longer applies to the current design of Shopify's admin and will no longer have any effect.	No

Was this page helpful?

Contextual Save Bar

Anchor to Plain JavaScriptPlain JavaScript

Anchor to Example codeExample code

Anchor to Create and showCreate and show

Anchor to Update optionsUpdate options

Anchor to HideHide

Anchor to Subscribe to Discard and SaveSubscribe to Discard and Save

Anchor to UnsubscribeUnsubscribe

Anchor to ReactReact

Anchor to [object Object], hookuseContextualSaveBar hook

Anchor to Example CodeExample Code

Anchor to APIAPI

Anchor to saveAction.setOptionssaveAction.setOptions

Anchor to discardAction.setOptionsdiscardAction.setOptions

Anchor to [object Object], componentContextualSaveBar component

Anchor to Example CodeExample Code

Anchor to PropsProps

Anchor to Shared APIsShared APIs

Anchor to [object Object]SaveActionOptions

Anchor to [object Object]DiscardActionOptions

Anchor to [object Object], hook`useContextualSaveBar` hook

Anchor to [object Object], component`ContextualSaveBar` component

Anchor to [object Object]`SaveActionOptions`

Anchor to [object Object]`DiscardActionOptions`