--- title: Toast API description: >- The Toast API provides temporary notification functionality for POS UI extensions, allowing you to display brief, non-intrusive messages to users for feedback, confirmations, and status updates that automatically disappear after a specified duration. Toast messages appear as overlay notifications that don't interrupt the user's workflow. api_version: 2024-10 api_name: pos-ui-extensions source_url: html: >- https://shopify.dev/docs/api/pos-ui-extensions/2024-10/target-apis/standard-apis/toast-api md: >- https://shopify.dev/docs/api/pos-ui-extensions/2024-10/target-apis/standard-apis/toast-api.md --- # Toast API The Toast API provides temporary notification functionality for POS UI extensions, allowing you to display brief, non-intrusive messages to users for feedback, confirmations, and status updates that automatically disappear after a specified duration. Toast messages appear as overlay notifications that don't interrupt the user's workflow. #### Use cases * **Action feedback:** Provide immediate feedback for successful data saves or API call completions. * **Error messages:** Display error messages and warnings without blocking workflow. * **Progress updates:** Show progress updates for long-running operations. * **Status changes:** Communicate system status changes like connectivity issues. Support Targets (17) ### Supported targets * [pos.​customer-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/customer-details#customer-details-action-menu-item-) * [pos.​customer-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/customer-details#customer-details-action-modal-) * [pos.​customer-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/customer-details#customer-details-block-) * [pos.​draft-order-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/draft-order-details#draft-order-details-action-menu-item-) * [pos.​draft-order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/draft-order-details#draft-order-details-action-modal-) * [pos.​draft-order-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/draft-order-details#draft-order-details-block-) * [pos.​home.​modal.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/home-screen#home-screen-action-modal-) * [pos.​home.​tile.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/home-screen#home-screen-tile-) * [pos.​order-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/order-details#order-details-action-menu-item-) * [pos.​order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/order-details#order-details-action-modal-) * [pos.​order-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/order-details#order-details-block-) * [pos.​product-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/product-details#product-details-action-menu-item-) * [pos.​product-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/product-details#product-details-action-modal-) * [pos.​product-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/product-details#product-details-block-) * [pos.​purchase.​post.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/post-purchase#post-purchase-action-menu-item-) * [pos.​purchase.​post.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/post-purchase#post-purchase-action-modal-) * [pos.​purchase.​post.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/post-purchase#post-purchase-block-) ## ToastApi The `ToastApi` object provides methods for displaying temporary notification messages. Access these methods through `api.toast` to show user feedback and status updates. * show (content: string, options?: ShowToastOptions) => void required Displays a toast notification with the specified text content. The message appears as a temporary overlay that automatically dismisses after the specified duration. Use for providing immediate user feedback, confirming actions, or communicating status updates without interrupting the user's workflow. ### ShowToastOptions Specifies configuration options for displaying toast notifications. Controls the duration and display behavior of temporary notification messages. * duration The duration in milliseconds that the toast message remains visible before automatically dismissing. If not specified, the toast uses the default system duration (typically 3-5 seconds depending on the platform). Shorter durations (1000-2000ms) work well for simple confirmations like "Item added" or "Saved". Longer durations (5000-7000ms) provide adequate reading time for important messages or multi-sentence notifications. Very short durations (< 1000ms) may not give users enough time to read the message. The toast dismisses automatically after the specified duration, but users may also manually dismiss it if the system supports swipe-to-dismiss gestures. ```ts number ``` ```ts export interface ShowToastOptions { /** * The duration in milliseconds that the toast message remains visible before automatically dismissing. If not specified, the toast uses the default system duration (typically 3-5 seconds depending on the platform). * * Shorter durations (1000-2000ms) work well for simple confirmations like "Item added" or "Saved". Longer durations (5000-7000ms) provide adequate reading time for important messages or multi-sentence notifications. Very short durations (< 1000ms) may not give users enough time to read the message. The toast dismisses automatically after the specified duration, but users may also manually dismiss it if the system supports swipe-to-dismiss gestures. */ duration?: number; } ``` Examples ### Examples * #### Show a toast notification ##### Description Display a brief, non-intrusive notification message that automatically dismisses. This example demonstrates using \`toast.show()\` to provide immediate feedback after user actions, confirmations for successful operations, or status updates without interrupting the merchant's workflow. ##### React ```tsx import React from 'react'; import { Tile, useApi, reactExtension, } from '@shopify/ui-extensions-react/point-of-sale'; const SmartGridTile = () => { const api = useApi<'pos.home.tile.render'>(); return ( api.toast.show('Toast content', 5000)} enabled /> ); }; export default reactExtension('pos.home.tile.render', () => ); ``` ##### TS ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', onPress: () => api.toast.show('Toast content', 5000), enabled: true, }); root.append(tile); }); ``` ## Best practices * **Use appropriate timing:** Choose duration values that give users enough time to read the message without keeping notifications visible longer than necessary. * **Provide meaningful feedback:** Use toast messages to confirm successful actions, explain errors clearly, or communicate important status changes that users need to know about. * **Avoid overuse:** Reserve toast notifications for important feedback and avoid showing multiple toasts simultaneously, as this can overwhelm users and reduce the effectiveness of the notifications. ## Limitations * Toast messages are temporary and can't be made persistent. For important information that users need to reference later, consider using other UI components or storage mechanisms. * Multiple toast messages may overlap or interfere with each other if shown in rapid succession. Consider queuing or spacing out notifications appropriately. * Toast content is limited to plain text and can't include rich formatting, links, or interactive elements.