Contextual Save Bar
Display the contextual save bar to indicate that a form on the current page contains unsaved information, or when the merchant 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 merchant.
There are 3 ways to use the contextual save bar:
- Plain JavaScript
- React hook
- React component
Plain JavaScript
Anchor link to section titled "Plain JavaScript"Example code
Anchor link to section titled "Example 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.
Create and show
Anchor link to section titled "Create and show"Create a contextual save bar instance with some initial options. Then dispatch a SHOW
action to display it on the page.
Update options
Anchor link to section titled "Update 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.
Dispatch a HIDE
action when you want to hide the contextual save bar.
Subscribe to Discard and Save
Anchor link to section titled "Subscribe 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 merchant 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.
Unsubscribe
Anchor link to section titled "Unsubscribe"Call the unsubscribe
method to remove all current subscriptions on the contextual save bar.
The App Bridge React library supports two ways of using the contextual save bar action.
You can use either the hook or the component to add a contextual save bar to the app.
useContextualSaveBar
is a hook that accepts no arguments and returns an object with the following methods and objects:
show: ({fullWidth?: boolean; leaveConfirmationDisabled?: boolean}) => void;
hide: () => void;
saveAction: { setOptions: (options: SaveActionOptions) => void };
discardAction: { setOptions: (options: DiscardActionOptions) => void };
See Props for complete API descriptions for these methods and objects.
Example Code
Anchor link to section titled "Example Code"
ContextualSaveBar
is a component that accepts props.
Example Code
Anchor link to section titled "Example Code"
useContextualSaveBar props
Anchor link to section titled "useContextualSaveBar props"The useContextualSaveBar
hook does not accept any props. The APIs for the methods and objects that the hook returns are as follows:
show
Name | Type | Description | Required |
---|---|---|---|
fullWidth | boolean |
Whether the contextual save bar should fill the entire screen width | No |
leaveConfirmationDisabled | boolean |
Whether to show a confirmation modal after the user navigates away from the page | No |
hide
No arguments.
saveAction.setOptions
Anchor link to section titled "saveAction.setOptions"See SaveActionOptions
.
discardAction.setOptions
Anchor link to section titled "discardAction.setOptions"See DiscardActionOptions
.
ContextualSaveBar props
Anchor link to section titled "ContextualSaveBar props"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 |
Shared APIs
Anchor link to section titled "Shared APIs"Both the ContextualSaveBar component and the useContextualSaveBar hook make use of the following types.
SaveActionOptions
Anchor link to section titled "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 |
DiscardActionOptions
Anchor link to section titled "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 | No |