Shopify’s latest POS Navigation API enhancement introduces the navigatesuccess event, giving developers a reliable signal that a screen’s native transition has fully completed. This post breaks down the change, identifies who needs to pay attention, and provides clear, actionable steps to integrate the new event into your POS UI extensions.
What Changed: The navigatesuccess Event
The POS Navigation API now fires a navigatesuccess event after the destination screen finishes its native transition. Unlike currententrychange, which can trigger before the UI is fully visible, and the navigate() promise, which resolves without waiting for the animation, navigatesuccess guarantees the screen is on‑screen and ready for interaction.
Who Is Affected
Only POS UI extensions that target API version 2026-10 and run on POS builds that support the new event will see navigatesuccess. Merchants using older POS hardware or extensions built against previous API versions won’t receive the event, but they also won’t be broken—no migration is required.
How to Listen for navigatesuccess
Add a listener on the screen that will become visible after navigation. When navigating back, attach the listener to the screen that will re‑appear, because the screen you’re leaving gets removed from the DOM.
js
import {extension} from '@shopify/ui-extensions/pos';
export default extension('pos.navigation', (root, {navigation}) => {
// Register once the screen component mounts
navigation.addEventListener('navigatesuccess', (event) => {
console.log('Navigation completed for:', event.target);
// Your post‑navigation logic here (e.g., focus an input, fetch data)
});
// Example navigation trigger
const goToSettings = () => navigation.navigate('settings');
// ...attach goToSettings to a button click
});
Best Practices and Common Pitfalls
• Register on the destination screen – If you attach the listener on the screen you’re leaving, it will be removed before the event fires.
• Don’t rely on `navigate()` promise – It resolves as soon as the navigation request is sent, not when the UI finishes animating.
• Graceful fallback – Guard your code with a version check (if (navigation.on) …) so older POS builds simply skip the listener without error.
• Clean up listeners – If your screen can be unmounted, remove the listener to avoid memory leaks (navigation.removeEventListener('navigatesuccess', handler)).
Next Steps for Your Extension
apiVersion is set to 2026-10 or later in shopify.extension.toml.navigatesuccess listener wherever you previously depended on currententrychange or the navigation promise.Conclusion
The addition of navigatesuccess removes the guesswork around POS screen transitions, letting developers build smoother, more responsive extensions. No migration is needed, but updating your navigation logic now will future‑proof your app and improve the merchant experience. Have questions or want a deeper dive? Drop a comment below or reach out on the Shopify Community forums.
