Summary:
UI URL Query Param Based Rendering is Not Working as Expected in Forge Custom UI
Environment:
- Platform: Jira Cloud
- Framework: Atlassian Forge (Custom UI)
- Module: jira:globalPage
- Frontend: React (Custom UI)
- Bridge: @forge/bridge
Description:
I am building a Forge Custom UI app that replicates Tempo Timesheets functionality. The core requirement is to reflect the current UI filter state (date range, groupBy, viewType etc.) in the browser URL as query params — so that users can share, bookmark, and restore views using the URL.
Expected Behavior:
When a user changes a filter (e.g. date range, groupBy), the browser URL should update instantly with the new query params — without a full page reload — similar to how Tempo Timesheets works:
Actual Behavior:
The following approaches were tested and none achieved the expected result:
-
window.history.replaceState()
→ Only updates the iframe’s internal URL.
→ Parent browser address bar is NOT updated.
→ No page reload, but URL change is invisible to user. -
router.navigate() from @forge/bridge
→ Successfully updates the parent browser URL.
→ BUT causes a full page reload every time.
→ Not suitable for real-time filter interactions. -
window.location.hash (hash params)
→ Only affects iframe internal state.
→ Parent browser URL is NOT updated. -
view.createHistory() from @forge/bridge
→ Behavior is unclear and underdocumented.
→ It is not confirmed whether this updates the parent
browser URL without a full page reload.
→ Needs official clarification.
Questions:
- Is there any officially supported way in Forge Custom UI to update the parent browser URL query params WITHOUT a full page reload?
- Does view.createHistory() achieve this? If yes, is there a working example for jira:globalPage?
- Is this a known limitation of the Forge iframe sandbox model?
- If this is a gap, is it on the Forge roadmap — especially given the active Connect → Forge migration?
Impact:
This is a critical functionality gap for apps migrating from Atlassian Connect to Forge. Connect apps (like Tempo) have direct access to the parent page URL and can update it freely. Forge’s sandboxed iframe model prevents this, making it difficult to build feature-equivalent apps on Forge.
This affects:
- Shareability of app views via URL
- Bookmarkable filter states
- Deep linking to specific app states
- Connect → Forge migration parity
Requested Action:
- Official clarification on whether this is possible in Forge today
- If not possible, request this be added to the Forge roadmap as a priority item given Connect deprecation timeline (Q4 2026)