containers
Navigation history & breadcrumbs: Phase 1 design
UX Description
Create a finished design for Phase 1 navigation history implementation:
- Back/forward button visuals and placement in title bar
- Button states (enabled, disabled, hover, pressed)
- Integration with existing title bar elements
Request type
None
Primary Contact
No response
Deadline for request
No response
I will work on the buttons design going forward, but as far as action is concerned, I think we can to a point follow best practices of other apps utilized by developers. For example, in the flow of how back and forth buttons actually work. Let's look at Cursor as a great example.
Navigation logic in Cursor as defined by Gemini:
đź’» Core Navigation Logic
The system maintains a chronological record of the places you've been (pages, folders, or, in a code editor, cursor positions/file views).
1. The History List
- Every time you actively move to a new location—by clicking a link, opening a file, or in a code editor, performing a "Go to Definition"—that new location is added to the end of the history list.
2. The Current Position
- A pointer or index keeps track of your current position within this history list.
3. The "Go Back" Action (Undo Navigation)
- When you click the "Back" button, the system moves the current position pointer one step backward in the history list.
- The application then displays the item (web page, file, or code position) at that new, previous index.
4. The "Go Forward" Action (Redo Navigation)
- The "Forward" button is only active if you have previously used the "Back" button (i.e., if the current position pointer is not at the very end of the list).
- When you click "Forward," the system moves the current position pointer one step forward in the history list.
- The application displays the location at that next index, effectively reversing the "Back" action.
🔄 What Happens When You Add a New Item
The most crucial piece of logic occurs when you are in the middle of the history list (you've pressed Back one or more times) and then navigate to a new location:
- Any entries in the history list that were after your current position (the ones you could have used Forward to reach) are discarded.
- The new location is then added to the end of the now-shortened list, becoming the new current position.
Example:
- Visit Page A $\rightarrow$ Page B $\rightarrow$ Page C. (History: A, B, C | Current: C)
- Press Back. (History: A, B, C | Current: B)
- Press Back again. (History: A, B, C | Current: A)
- Navigate to Page D.
- C and B are discarded. (History: A, D | Current: D)
- You can now only press Back to go to A, and you cannot go Forward to C or B.
Thanks, @MariaLeonova, for the outline. A couple of comments:
There's no mention of the edge cases the team discussed:
- What happens when the user navigates back to a container detail page, but that container has been deleted since?
- Similarly, if a machine is stopped, can the user still navigate to pages that depend on it?
- How about form inputs and search queries? Should they be restored when navigating back?
There's no mention of the history limits. How many pages should be kept in the navigation history? I believe we should set a meaningful limit. 20 items perhaps?
We also discussed if history should reset on PD launch or persist across sessions (we mostly agreed that the reset is the way). Please mention it in the list.
There's a big challenge too: extensions (like AI Lab, Kubernetes) currently maintain their own breadcrumb systems and wouldn't contribute to our navigation history. We should mention this limitation and note that it's blocked until the extension API work is complete.
These were discussed in our UX Check-Ins (November 6 and 13) and should be addressed in the design.
For the Phase 1 design (this issue), please work on these too:
- Scope clarification: for Phase 1, we're implementing basic back/forward features, inspired by standard web browsers. What about the edge cases (see above)? What would be shown? A placeholder page? Error message? Or would we prevent navigation altogether?
- Please decide on the history limits. We can also say that the history limit will be based on what we figure out from the telemetry, but I'd be happy even if you say something like "20".
Please keep in mind what's out of the Phase 1:
- form state restoration,
- keyboard shortcuts,
- history dropdown menu.
@vancura great questions all and thank you for bringing them up. I would appreciate your input on them as well, since this is a joint effort.
What happens when the user navigates back to a container detail page, but that container has been deleted since?
Is the page still there? If not, the back button would be disabled, I believe. Here's Gemini's summary of what happens in Cursor:
Summary in a Code Editor (Like Cursor)
In a code editor, the navigation history is simpler and more reliable.
If a user tries to go back to a file or position that is no longer "available" (e.g., the file was deleted or moved),
the editor will typically:
- Stop at the previous valid location in the stack.
- If the previous location was the deleted file, it will likely try to open the file and either show an "File Not Found" error
in a new tab or simply skip that history entry and jump to the next valid location further back in the stack.
Similarly, if a machine is stopped, can the user still navigate to pages that depend on it?
Same question as above.
How about form inputs and search queries? Should they be restored when navigating back?
AFAIK, form inputs and search queries are generally preserved when navigating back and forth, but I would be interested too hear your opinion.
History limits Depending on technical feasibility and memory amount needed, I'd say 20 sounds reasonable; however higher number could also be feasible.
Constraints
Thank you for specifying these; please also add them to the issue description, so it's very clear during implementation phase.
@vancura do these arrows have to function in both Kortex and Podman Desktop in the same way?
Dark mode:
back arrow active, forward arrow hover
Light mode:
back arrow hover, forth arrow active
Please see variants here: in Figma
Awesome work, @MariaLeonova!
(Deleted container navigation) — Is the page still there? If not, the back button would be disabled, I believe.
During the UX meeting, we discussed three options:
- Show a placeholder page with "This container no longer exists" + link to the list
- Fall back to the list view (but @benoitf warned this could cause visual glitches)
- Skip the invalid entry and jump to the next valid location in history.
For Phase 1, I recommend Option 1 (placeholder page). It's the easiest solution, IMHO. It's also explicit, doesn't cause glitches, and doesn't silently skip history entries, which could confuse users.
(Stopped machines) — Similarly, if a machine is stopped, can the user still navigate to pages that depend on it?
This is different from deleted resources. A stopped machine is still a valid resource, but in a different state. We should allow the navigation in that case. The page would render, but show that the machine is stopped.
(Form inputs and search queries) — How about form inputs and search queries? Should they be restored when navigating back?
I don't know the exact technical constraints here, maybe somebody from the team can add their insight?
Anyways, for Phase 1, I suggest:
- Search queries: YES, preserve them (store query string in history entry)
- Form inputs: NO, this is explicitly out of Phase 1 scope (complex, can lead to data issues)
- History limits: 20 is good. We can adjust based on telemetry later.
- Session persistence: As discussed, history resets on app restart for Phase 1.
I'll add the constraints to the parent issue description.
Do these arrows have to function in both Kortex and Podman Desktop in the same way?
Yes, it can work the same way:
@Firewall @slemeur PTAL - this concerns both Podman Desktop and Kortex navigation.
We discussed a couple of things at the last UX meeting:
- Handling deleted resources: When the user returns to a deleted resource, we discussed showing a placeholder page with the title "This container no longer exists" and a link to the list. This is the right solution for Phase 1 because:
- it shows an explicit message that prevents user confusion,
- it will avoid visual glitches that @benoitf warned about
- it doesn't silently skip history entries (which could confuse users)
- and is simpler to implement.
- The difference between navigating to a stopped vs. deleted resources:
- when navigating to a deleted resource: we will show a placeholder page (see above)
- when navigating to a stopped machine: we will allow navigation, but the page will show a stopped state of that machine, because it's still a valid resource, just in a different state (that's different from a deleted container).
- Regarding form inputs and search queries, we discussed that:
- we WILL preserve search queries (by storing the query string in the history entry),
- we WILL NOT preserve form inputs (out of the scope for Phase 1)
-
We confirmed that 20 items in the history limit is the right number, but we may adjust based on telemetry later. We need the telemetry, though (/cc @Firewall)
-
Session persistence: history resets on app restart.
-
Extensions (like AI Lab, Kubernetes) currently have their own breadcrumbs systems and would not contribute to our new navigation history. We'll see what to do when the extension API is complete.
Here are 3 options for navigation button placement and style.
- to the left, next to traffic lights. This will maintain the current placement of search
- in the center, with search field outlines. This one's my least favourite as it grabs too much attention
- in the center, next to search, slightly better visually aligned.
Thank you for the review! Here's the Figma file. This should be ready for implementation for phase 1, @vancura.
@vancura I'm going to close this, since the design for Phase 1 is done. Additional work and implementation can be tracked as part of the parent issue.