<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=598975) </details> <!--IssueSummary end--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=598975) </details> ## Summary This is a follow-up to [!228795](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/228795) ("Add column sorting capability to GitLab tables") and the related discussion issue https://gitlab.com/gitlab-org/gitlab/-/work_items/597033. > **Scope note:** The primary focus of this issue is the **clear sort** feature and **tooltips on sort icons**. The additional items below are lower-priority considerations to revisit based on user feedback. Two UX improvements were raised in MR discussions that were deferred for a follow-up: --- ## 1. Add tooltips to sort icons Sort icons in table column headers currently have no tooltip or accessible label explaining their meaning or current state. This creates two problems: - **Discoverability**: Users may not understand that clicking a column header will sort the table. - **Accessibility**: Screen readers and keyboard users have no context for what the icon represents or what action clicking it will perform. ### Proposed solution - Add a `GlTooltip` (or `title` attribute) to the sort icon in each column header. - Tooltip text should reflect the **current sort state** and the **next action**, for example: - When unsorted: `"Sort ascending"` - When sorted ascending: `"Sort descending"` - When sorted descending: `"Clear sort"` (if clear sort is implemented) or `"Sort ascending"` - Ensure `aria-label` is also set appropriately for screen reader support. --- ## 2. Add a way to clear/reset sorting The current implementation has no way to return to the original (unsorted) table order without a full page reload. The flow is: 1. Click column → sort ascending 2. Click again → sort descending 3. No further action available to reset This may be confusing or frustrating for users who want to return to the natural document order after exploring a sorted view. ### Proposed solution Decide on and implement a clear sort affordance. Options to consider (discussed in https://gitlab.com/gitlab-org/gitlab/-/work_items/597033): - **Third click cycles back to unsorted**: Clicking the currently-active sort column a third time resets to the original order. Simple, no extra UI needed. - **✕ icon next to the active sort indicator**: A small dismiss/clear icon appears next to the sort arrow when a column is actively sorted, allowing one-click reset. - **Reset button in the table header area**: A dedicated "Reset sort" or "Clear sort" button appears when any sort is active. The third-click approach is likely the lowest-friction option and aligns with common table UX patterns. --- ## 3. Show sort arrows on hover Sort arrows (indicators) should be visible when a user hovers over a column header, even if the column is not currently sorted. This improves discoverability by giving users a visual cue that the column is sortable before they click. ### Proposed solution - Display the sort arrow icon in a muted/inactive style when the user hovers over an unsorted column header. - The arrow should only become fully visible (active style) once the column is sorted. - This pattern is consistent with common table UX conventions and helps users discover sortable columns without cluttering the UI at rest. --- ## Future considerations (pending user feedback) The following items are not in scope for this issue but should be revisited once the feature has been rolled out and feedback has been collected: ### Extend sorting to HTML tables Sorting is currently only supported for Markdown tables. There is an open question (see [this comment on !228795](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/228795#note_3265736387)) about whether HTML tables rendered in GitLab should also support column sorting. This will be driven by user feedback. A related concern raised during MR review: when a Markdown table is converted to HTML (for example, because it contains block elements), an alert warning is shown at conversion time — but on a return visit, the HTML table looks visually identical to a Markdown table, until sorting fails silently. Users have no way to tell their table is HTML and therefore not sortable. A good follow-up would be to surface a tooltip or indicator on unsortable tables explaining why sorting is unavailable. ### Revisit date and number sorting A previous iteration of this feature included date and number-aware sorting, but it was removed or deferred. Once the core feature is stable and feedback is in, it may be worth reintroducing smarter sorting for numeric and date columns with a better implementation. --- ## References - Initial (closed) MR introducing sortable columns: [!228795](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/228795) - Actual MR introducting sortable tables: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/239559+ - Discussion issue on clear sort: https://gitlab.com/gitlab-org/gitlab/-/work_items/597033 - Feature flag rollout issue: https://gitlab.com/gitlab-org/gitlab/-/work_items/597031 - Closed follow-up (code comment question): https://gitlab.com/gitlab-org/gitlab/-/work_items/598973