Tooltips or static help texts? #9648

New Issue

GiteaMirror · 2025-11-02T08:45:27-06:00

GiteaMirror commented

2025-11-02 08:45:27 -06:00

Originally created by @delvh on GitHub (Oct 2, 2022).

We need clarity on when to use tooltips versus when to use static help texts to describe features.
We certainly need at least one of them for many things that aren't immediately obvious (see i.e. #21306).

PRO tooltips

only shown when actually necessary
they don't shift user focus from the most important UI components to the mostly irrelevant help text
whenever you navigate on the page
easy to implement (class="tooltip" data-content="Tooltip content")

CONTRA tooltips

Requires JS to work

PRO static help text

does not require JS
-> no unexpected errors

CONTRA static help text

(for me) unclear, what you need to do to add one
(do you only need class="help", or do other fomantic UI classes need to be present as well?
In parent elements?)
Always grabs user focus, even on pages/screens where you have to be selective on what to present
Slightly larger HTML response size

Originally created by @delvh on GitHub (Oct 2, 2022). We need clarity on when to use tooltips versus when to use static help texts to describe features. We certainly need at least one of them for many things that aren't immediately obvious (see i.e. #21306). ## PRO tooltips - only shown when actually necessary - they don't shift user focus from the most important UI components to the mostly irrelevant help text whenever you navigate on the page - easy to implement (`class="tooltip" data-content="Tooltip content"`) ## CONTRA tooltips - Requires JS to work ## PRO static help text - does not require JS - -> no unexpected errors ## CONTRA static help text - (for me) unclear, what you need to do to add one (do you only need `class="help"`, or do other fomantic UI classes need to be present as well? In parent elements?) - **Always** grabs user focus, even on pages/screens where you have to be selective on what to present - Slightly larger HTML response size

GiteaMirror added the type/question label 2025-11-02 08:45:27 -06:00

GiteaMirror commented

2025-11-02 08:45:27 -06:00

@lunny commented on GitHub (Mar 29, 2023):

Maybe a clarify documentation under development could resolve the problem?

@lunny commented on GitHub (Mar 29, 2023): Maybe a clarify documentation under development could resolve the problem?

GiteaMirror commented

2025-11-02 08:45:28 -06:00

@delvh commented on GitHub (Mar 29, 2023):

Yes, but so far there hasn't been any discussion under this forgotten issue, so I don't know which to choose.

@delvh commented on GitHub (Mar 29, 2023): Yes, but so far there hasn't been any discussion under this forgotten issue, so I don't know which to choose.

GiteaMirror commented

2025-11-02 08:45:28 -06:00

@wxiaoguang commented on GitHub (Mar 29, 2023):

I guess the answer is: use "tooltip-data-content" as much as possible, because it shows faster than title. If the tooltip doesn't fit (like the DiffTreeItem), then fallback to title.

@wxiaoguang commented on GitHub (Mar 29, 2023): I guess the answer is: use "tooltip-data-content" as much as possible, because it shows faster than `title`. If the tooltip doesn't fit (like the DiffTreeItem), then fallback to `title`.

GiteaMirror commented

2025-11-02 08:45:28 -06:00

@delvh commented on GitHub (Mar 29, 2023):

Yes, but that is only part of the question.
This was especially intended with regard to the setting pages, as we often show helper texts there.
Or should the definition be as follows?

settings use the static help text
else if tooltip is possible (so no Vue yet), use a tooltip
else fallback to title

@delvh commented on GitHub (Mar 29, 2023): Yes, but that is only part of the question. This was especially intended with regard to the setting pages, as we often show helper texts there. Or should the definition be as follows? - settings use the static help text - else if tooltip is possible (so no Vue yet), use a tooltip - else fallback to `title`

GiteaMirror commented

2025-11-02 08:45:28 -06:00

@wxiaoguang commented on GitHub (Mar 29, 2023):

settings use the static help text (comment: if it looks good)
else if tooltip (comment: if it looks good)
else fallback to title

I could agree, if the "each" looks good.

... (so no Vue yet), use a tooltip

Vue already supports tooltip transparently. See my #23574

@wxiaoguang commented on GitHub (Mar 29, 2023): > settings use the static help text (comment: if it looks good) > else if tooltip (comment: if it looks good) > else fallback to title I could agree, if the "each" looks good. ---- > ... (so no Vue yet), use a tooltip Vue already supports tooltip transparently. See my #23574

GiteaMirror commented

2025-11-02 08:45:29 -06:00

@lunny commented on GitHub (Apr 12, 2023):

I vote to use static text as possible. It's clear and with no hidden. Tooltip likes a detailed explanation of a UI element. i.e. when hovering a #111, Gitea will pop up a floating window.

@lunny commented on GitHub (Apr 12, 2023): I vote to use static text as possible. It's clear and with no hidden. Tooltip likes a detailed explanation of a UI element. i.e. when hovering a `#111`, Gitea will pop up a floating window.

GiteaMirror commented

2025-11-02 08:45:29 -06:00

@delvh commented on GitHub (Apr 12, 2023):

Hmm, as I said: I only partially agree.
From a UX perspective, tooltips are a great invention: They don't take away any of the sparse space on the screen, and subsequently only attract attention when hovered over.
On normal pages, we simply don't have the space to display help texts.
So yes, using static help texts seems most applicable to describe what setting boxes do.
For individual settings, however, I recommend normal tooltips as seen in #21306.

@delvh commented on GitHub (Apr 12, 2023): Hmm, as I said: I only partially agree. From a UX perspective, tooltips are a great invention: They don't take away any of the sparse space on the screen, and subsequently only attract attention when hovered over. On normal pages, we simply don't have the space to display help texts. So yes, using static help texts seems most applicable to describe what setting boxes do. For individual settings, however, I recommend normal tooltips as seen in #21306.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#9648