Page MenuHomePhabricator

[Minerva TOC] Implement floating button + TOC position
Closed, ResolvedPublic3 Estimated Story Points

Description

User story

As a mobile user, I want easy access to the TOC through a floating button

Requirements

Implement a floating button that toggles a TOC overlay on/off.
This ticket is about both the button & TOC container design & placement.

Note that we need to consider interaction with the silly Minerva toast component that appears at the bottom sometimes.
Newcomers might also have the help button in the bottom right corner in that same area on some article namespaces (communities can define which namespaces show the help button in read mode through their local community configuration)

Design

https://phabricator.wikimedia.org/T410325#11413373

Acceptance criteria

  • This is no button on pages that have no TOC
  • There is a button at the bottom of the page that matches design
  • There is a TOC overlay that matches design
  • The button toggles the TOC overlay (open/close)
  • The button does not interfere with other elements (such as Minerva toast, help button, or other overlays like MMV or ImageBrowsing)
  • Nice to have: both button and TOC state accurately reflect url hash (#toc) and update as it changes

Event Timeline

egardner moved this task from Incoming/Inbox to Needs Refinement on the Reader Growth Team board.
egardner set the point value for this task to 3.Jan 14 2026, 5:23 PM
egardner moved this task from Needs Refinement to Ready on the Reader Growth Team board.

The button does not interfere with other elements (such as Minerva toast, help button, or other overlays like MMV or ImageBrowsing)

I found no issues with elements that may interfere with the floating button on the article page. This includes: blue link previews, Minerva toast (mw.notify method, mw-notification-area class), MMV overlay, ImageBrowsing overlay (?imageBrowsing=1), Edit overlay, Related articles, navigation menu (side nav on wider screens).

  • Is there a configuration to show the help button? (I haven't tested the help button)
  • Are there other toast notifications that I should be aware of?
  • Other: I assume the floating button can interfere with the PDF download. I don't have an example and tried applying class="noprint" (Template:Noprint) to hide the element from the printable version.

Change #1233855 had a related patch set uploaded (by LWatson; author: LWatson):

[mediawiki/extensions/ReaderExperiments@master] Minerva TOC: floating button styles

https://gerrit.wikimedia.org/r/1233855

Test wiki created on Patch demo by Mmullie (WMF) using patch(es) linked to this task:
https://740e6eaae6.catalyst.wmcloud.org/w/

@JScherer-WMF 2 questions about this button:

  • looks like there's a bunch of padding on both sides of the icon/text, which is not there when the button is the another state. It feels a bit odd to me that the appearance changes when clicked, so I was wondering whether this difference is intentional or not? See https://740e6eaae6.catalyst.wmcloud.org/wiki/Berlin?useskin=minerva&useparsoid=0&mpo=minerva-toc-button:treatment for what it looks like.
  • they seem to have different colors - am I right to assume that those colors are meant to signify the difference in state (TOC open vs closed), or is it some interaction color (hover/click)?

image.png (1×720 px, 158 KB)

image.png (1×720 px, 340 KB)

  • Is there a configuration to show the help button? (I haven't tested the help button)

I'm also not sure how/where that help button lives exactly - @JScherer-WMF do you know?

@JScherer-WMF

  • How should the new Table of Contents (TOC) behave on wider viewports? Do you have a specific design in mind, or should I follow the Minerva and Vector TOC patterns for inspiration? Currently, the TOC occupies the majority of the screen across all sizes. Should I address this responsiveness now or track it for a future iteration?
  • There are two versions of the floating action button: one with a label and an icon, and an icon-only variant. Is the icon-only version intended for layouts where space is limited or where a label might obstruct other UI elements?

Change #1233855 merged by jenkins-bot:

[mediawiki/extensions/ReaderExperiments@master] Minerva TOC: floating button styles

https://gerrit.wikimedia.org/r/1233855

Regarding the editor help button: I logged in and enabled the newcomer homepage

Editors can toggle this feature at Special:Preferences → User profile → Newcomer editor features → Display newcomer homepage.

... but I don't see the help button or help panel appearing.

Also, the task description mentions https://en.wikipedia.org/wiki/Wikipedia:Growth_Team_features#Community_configuration

Change #1234439 had a related patch set uploaded (by LWatson; author: LWatson):

[mediawiki/extensions/ReaderExperiments@master] Minerva TOC: add interactive states

https://gerrit.wikimedia.org/r/1234439

Change #1234454 had a related patch set uploaded (by Matthias Mullie; author: Matthias Mullie):

[mediawiki/extensions/ReaderExperiments@master] Use toggle button & use --active color for 'pressed'

https://gerrit.wikimedia.org/r/1234454

Regarding the editor help button: I logged in and enabled the newcomer homepage

Editors can toggle this feature at Special:Preferences → User profile → Newcomer editor features → Display newcomer homepage.

... but I don't see the help button or help panel appearing.

Also, the task description mentions https://en.wikipedia.org/wiki/Wikipedia:Growth_Team_features#Community_configuration

I'm not 100% sure where these come from. @nayoub @KStoller-WMF any ideas how we can reliably trigger the new editor help button?

To generate the toast, you can change something in settings.

Hey @JScherer-WMF - I'm sharing two patchdemo links for you to review. Hoping to get clarity on the button's "active" state.

  1. Codex Button with hover and active states. Patchdemo: https://fc4fd601e6.catalyst.wmcloud.org/w/index.php?title=Berlin&mpo=minerva-toc-button%3Atreatment
  2. Codex ToggleButton with toggled on (TOC is open), toggled off (TOC is closed), and hover states. The main difference is that the "active" state is applied when the toggle button is toggled on (instead of when actively pressed). Patchdemo: https://856fdaa909.catalyst.wmcloud.org/w/index.php?title=Berlin&mpo=minerva-toc-button%3Atreatment

Which approach aligns with your design?

Hey @JScherer-WMF, thanks for the ping.
You can enable it on your preferences: at Special:Preferences → User profile → Newcomer editor features → Enable the editor help panel
And then you should see it when you edit an article in VE or Wikitext :)

Note that each wiki can decide which Namespaces the help panel is available, via Community Configuration.
Example for enwiki: https://en.wikipedia.org/wiki/Special:CommunityConfiguration/HelpPanel

So keep that in mind when testing, etc. https://test.wikipedia.org/wiki/Special:CommunityConfiguration/HelpPanel

Thanks for your help @JScherer-WMF @nayoub @KStoller-WMF ! I'm able to test in edit mode 😄

Change #1235003 had a related patch set uploaded (by LWatson; author: LWatson):

[mediawiki/extensions/ReaderExperiments@master] Minerva TOC, button: ensure no conflict with page overlays

https://gerrit.wikimedia.org/r/1235003

Update about the floating button conflicting with other page overlays:

Patch 1235003 addresses the overlay issues mentioned below.

Screenshots shared from Apple Simulator iPhone14 Pro iOS 16.0. Triggered a toast notification with mw.notify("hello") in the browser console.

Minerva toast
Problem: The toast notification overlaps the floating button. It's not ideal, even if the notification is auto-dismissible and temporarily visible.

minerva-toc--button--toggled-on overlapped by toast.png (2×1 px, 676 KB)

Solution: Adjust positioning for toast notifications
Repositioned the button and Table of Contents (TOC) further from the bottom of the viewport when a toast notification is visible to prevent visual overlap.

minerva toc--button toc closed with toast msg.png (2×1 px, 2 MB)
minerva toc--button toc open with toast msg.png (2×1 px, 886 KB)

Editor overlay
Problem: The button is visible in edit mode, particularly within the Visual Editor (VE).

minerva-toc--button conflicts with editor overlay-ve.png (1×754 px, 256 KB)

Solution: Hide the floating button during editing.
Target the general .editor-overlay selector instead of the specific .editor-overlay-ve selector to ensure broader coverage across the different editor types (wikitext and VE).

Change #1235190 had a related patch set uploaded (by LWatson; author: LWatson):

[mediawiki/extensions/ReaderExperiments@master] Minerva TOC button: responsiveness, support touch devices

https://gerrit.wikimedia.org/r/1235190

@JScherer-WMF Please disregard my previous request T413401#11563957. I'll wait for a formal design review next week. The toggle button is better suited for this use case because it handles the toc open/closed states. In the meantime, let's proceed with the code review for the toggle button implementation (cc: @matthiasmullie). I can address any design adjustments in a follow-up patch next week.

This is a patchdemo of the latest code changes (including open patches): https://482bd7320e.catalyst.wmcloud.org/wiki/Alfalfa?mpo=minerva-toc-button:treatment. Navigate to the URL and enable mobile view using the link at the bottom of the page to toggle mobile/desktop.

Change #1234439 merged by jenkins-bot:

[mediawiki/extensions/ReaderExperiments@master] Minerva TOC: add interactive states

https://gerrit.wikimedia.org/r/1234439

Change #1234454 merged by jenkins-bot:

[mediawiki/extensions/ReaderExperiments@master] Use toggle button & use --active color for 'on'

https://gerrit.wikimedia.org/r/1234454

Change #1235190 merged by jenkins-bot:

[mediawiki/extensions/ReaderExperiments@master] Minerva TOC button: responsiveness, support touch devices

https://gerrit.wikimedia.org/r/1235190

Change #1235343 had a related patch set uploaded (by Matthias Mullie; author: Matthias Mullie):

[mediawiki/extensions/ReaderExperiments@master] Don't show TOC unless there is one

https://gerrit.wikimedia.org/r/1235343

Change #1235003 merged by jenkins-bot:

[mediawiki/extensions/ReaderExperiments@master] Minerva TOC button: ensure no conflict with page overlays

https://gerrit.wikimedia.org/r/1235003

Change #1235343 merged by jenkins-bot:

[mediawiki/extensions/ReaderExperiments@master] Don't show TOC unless there is one

https://gerrit.wikimedia.org/r/1235343

lwatson changed the task status from Open to In Progress.Jan 30 2026, 2:31 PM

Checked on enwiki beta - the specs are in place:

IMG_7821.PNG (640×296 px, 333 KB)
IMG_7822.PNG (1×828 px, 339 KB)

Super minor note: comparing with the design https://phabricator.wikimedia.org/T410325#11413373, the subheaders are placed on an equal space from above headers; the same spacing as between subheaders. The implementation has first subheaders placed closer to a header.

designenwiki beta
image.png (1×720 px, 158 KB)
IMG_7822.PNG (1×828 px, 416 KB)

Checked for

  • __NOTOC__ is respected
  • interference with Help panel - no issues

Screenshot 2026-02-05 at 4.39.03 PM.png (1×650 px, 249 KB)

  • interference with drawers for Suggested Edits (non-Structured edits) - yes, the SE drawer would cover the toc button. The drawer is meant to be dismissed by a user; there is no conflicting transparency issues between two elements

Screenshot 2026-02-05 at 5.07.12 PM.png (1×1 px, 1 MB)

  • mw-ge-collapsibleDrawer - aka the post-edit dialog. When the post-edit dialog collapsed, the toc button is partially peeks frome behinds the drawer:

Screenshot 2026-02-05 at 4.50.14 PM.png (756×1 px, 222 KB)

The same issue with the Leveling up dialog:
Screenshot 2026-02-05 at 4.45.41 PM.png (1×1 px, 260 KB)

bvibber subscribed.
  • Design & placement (purpose of task) is functional and matches design.
  • Oassed QA above.
  • Non-blocking issues: keyboard/accessible interactions do not work at this time, but we will follow up on that stuff later.

Changing status to _resolved_ :D

🎉

Filed T416939 for follow-up on accessibility.

Test wiki on Patch demo by Mmullie (WMF) using patch(es) linked to this task was deleted:

https://740e6eaae6.catalyst.wmcloud.org/w/

Change #1238410 had a related patch set uploaded (by Matthias Mullie; author: Matthias Mullie):

[mediawiki/extensions/ReaderExperiments@master] Fix padding between nested TOC items

https://gerrit.wikimedia.org/r/1238410

Change #1238410 merged by jenkins-bot:

[mediawiki/extensions/ReaderExperiments@master] Fix padding between nested TOC items

https://gerrit.wikimedia.org/r/1238410

Test wiki on Patch demo by LWatson-WMF using patch(es) linked to this task was deleted:

https://fc4fd601e6.catalyst.wmcloud.org/w/

Test wiki on Patch demo by LWatson-WMF using patch(es) linked to this task was deleted:

https://856fdaa909.catalyst.wmcloud.org/w/

Test wiki on Patch demo by LWatson-WMF using patch(es) linked to this task was deleted:

https://482bd7320e.catalyst.wmcloud.org/w/

Test wiki on Patch demo by LWatson-WMF using patch(es) linked to this task was deleted:

https://cbf2720cb4.catalyst.wmcloud.org/w/

Test wiki on Patch demo by LWatson-WMF using patch(es) linked to this task was deleted:

https://b0a5fc90a5.catalyst.wmcloud.org/w/

Test wiki on Patch demo by LWatson-WMF using patch(es) linked to this task was deleted:

https://005aba2041.catalyst.wmcloud.org/w/

Test wiki on Patch demo by LWatson-WMF using patch(es) linked to this task was deleted:

https://8f3fb21088.catalyst.wmcloud.org/w/