Skip to main content

just_tooltip 0.6.0 copy "just_tooltip: ^0.6.0" to clipboard
just_tooltip: ^0.6.0 copied to clipboard

A lightweight, customizable Flutter tooltip with flexible placement, hover, tap & keyboard triggers, screen-reader support, programmatic control, and RTL support.

0.6.0 #

Breaking #

  • A tooltip hides while a route covers it (#100). This changes behaviour with no code change: the new hideWhenCovered is on by default. See Migration to 0.6.0 in the README. A dialog, a page, a sheet or a menu drawn as a route pushed over a shown tooltip used to leave it shown underneath, and it was still shown after the route was popped; a tooltip opened by a tap or by controller.show() has no trigger that leaves, so nothing closed it. Measured in flutter_folderview: a label tooltip whose tap also opened a dialog stayed through the dialog and after it.
    • The new hideWhenCovered is on by default. A covered tooltip fades out and calls onHide, however it was opened. While covered it does not show: controller.show() is ignored, and a tap whose own gesture pushes the route never opens it. Once the route is current again it stays closed until something shows it; a pointer still over the child, or keyboard focus still in it, shows it again.
    • Only the nearest route counts: a route pushed on an outer Navigator does not cover a tooltip on a nested one. A menu drawn in the overlay (MenuAnchor, DropdownMenu, Autocomplete) is not a route and covers nothing. A tooltip whose own route is popped leaves with it, as before, usually without onHide.
    • hideWhenCovered: false keeps the old behaviour.

Added #

  • hideWhenCovered (bool, default true): whether a tooltip hides while a route covers it and refuses to show while covered (#100; see Breaking above).

Changed #

  • waitDuration delays only a tooltip that is hidden (#106). A pointer or keyboard focus returning to the child while the tooltip is still shown, or fading out, brings it back at once instead of waiting again, and a hover over a tooltip shown by controller.show() restarts showDuration from that moment. A controller.show() made while a hover waits cancels the wait.

  • The pointer moving onto an interactive tooltip that is fading out brings it back, as moving onto its child does (#134). Only the child did: with the pointer leaving the child and reaching the tooltip just after the 100 ms grace window, or crossing from the child onto it as showDuration ran out, the tooltip faded away under the pointer. It comes back without a second onShow, whatever began the fade — the grace window, showDuration, controller.hide(), Escape, or another tooltip taking its place in the registry, which then hides — and the same rules hold as for the child: a tooltip closed with Escape while keyboard focus is inside it, or one whose child was scrolled out of sight, stays closed. With enableHover: false the tooltip is not brought back.

  • The pointer resting on an interactive tooltip keeps it shown when keyboard focus leaves the child (#149). A tooltip shown by keyboard focus hid 100 ms after focus left, under a pointer resting on the tooltip, where a pointer resting on the child kept it. Now it stays, and so it does when enableFocus is turned off instead; it hides when the pointer leaves the tooltip: after the 100 ms grace window, or at once if enableHover has been turned off since the pointer came onto it. This holds only for a pointer that came to rest on the tooltip while enableHover was on — moved onto it, or left still where the tooltip appeared. Escape, controller.hide(), another tooltip taking its place, its child scrolled out of sight and a route covering it still hide it, and with showDuration the countdown still decides. A tooltip nested inside its child, in a registry of its own, does not hide it when keyboard focus reaches the nested one (see #156 below).

  • The pointer resting on an interactive tooltip wins over keyboard focus in a tooltip nested inside its child, as the pointer on the child already did (#156). With the nested tooltip in a registry of its own, keyboard focus moving onto it from inside the outer tooltip — Tab from a button in the outer child, say — hid the outer tooltip under the resting pointer. Now both stay shown, whatever came first; once the pointer leaves the tooltip, the focused nested tooltip takes over and the outer one hides. This holds only for a pointer that came to rest on the tooltip while enableHover was on.

Fixed #

  • onShow is called after the first frame a tooltip is drawn in, and onHide only for a show whose onShow was called (#103). onShow used to run as soon as a show began, so a tooltip removed before the next frame reported onShow and nothing else. Measured in flutter_folderview: a label tap whose onNodeTap removes the tooltip's content called onShow and nothing visible.

    • Every onShow, and the screen-reader announcement with it, now comes one frame later. A show that ends before its first frame — hidden, or removed — calls neither callback.
    • onHide is no longer called inside a build. A tooltip that lost its content with nothing left to fade called it from inside the rebuild.
    • A tooltip moved by a GlobalKey while fading out no longer calls onHide, as one that leaves the tree while shown already did not.
  • A tooltip moved by a GlobalKey fades in again on its next show (#109). Taking it out of the tree hid it at once but left its animation where it was, so the next show started at full opacity, or mid-fade, and a fade that was running kept running. Measured: opacity 1.0 on the first frame of the next show, against 0.0 for a fresh one.

  • A tooltip hidden by its registry comes back when the tooltip that took its place leaves the tree (#111). It came back only when that tooltip hid; one removed while shown or fading out left it hidden, with the pointer or focus still on its child. Measured in a widget test: tooltip A shown by hover, evicted by B's controller.show(), then B removed from the tree — A was not shown. A tooltip removed before it was shown brings nothing back.

  • A tooltip hidden by its registry comes back only once no tooltip in that registry holds the place (#113). It came back whenever any tooltip's show ended, and then hid the tooltip that held the place. Measured in widget tests: tooltip A shown by hover, evicted by D's controller.show(), D evicted by B's — when D's fade ended, A came back and B hid; and with A and B in one TooltipRegistry and C in another, B evicting A and then c.hide() brought A back and hid B. Now A comes back when B hides, and a show ending in another registry brings nothing back.

  • A tooltip whose registry changes while it is shown moves to the new one at once (#114). It stayed recorded in the old registry, whose next show still hid it, while its hide was reported to the new one. Measured in widget tests: tooltip T shown with registry: r1, rebuilt with registry: r2, and X's controller.show() in r1 hid T; and since #113 above, A hover-shown in r1 and evicted by X, X rebuilt with registry: r2, then x.hide() left A hidden.

    • Leaving a registry where it held the place brings back the tooltips it hid there, at once. Joining the new registry hides the tooltip shown there, as a show does — changing only the registry parameter can hide a tooltip.
    • A TooltipRegistry() created inside a parent's build gives every rebuild a new registry, and its tooltips move to it together: the one shown stays shown, and the ones it hid come back when it hides.
    • A tooltip hidden by its registry and then given another one waits there instead: it comes back at once when nothing is shown in the new registry, otherwise when that tooltip leaves. A tooltip fading out does not join the new registry.
  • A tooltip hidden by its registry stays hidden while the tooltip shown in its place is still shown, unless a new trigger brings it back (#116). Any change that re-checked its trigger showed it again, and hid the other tooltip. Measured in widget tests on one TooltipRegistry: tooltip A shown by hover and hidden by D's controller.show(), then A's message set to '' and back — A came back and D hid; and a tooltip shown by keyboard focus, hidden by another one's hover, then moved by a GlobalKey — it came back and the hovered one hid with the pointer still on it.

    • Now it comes back when the tooltip shown in its place hides, as #113 above already did for that path. Its content returning, its route becoming current again, a GlobalKey move, enableHover or enableFocus turned on, a nested tooltip under the pointer losing its content or leaving the tree, its child moving under a resting pointer, or the pointer or focus leaving while the other stays, no longer show it before then.
    • A new trigger still shows it at once and hides the other tooltip, as before: the pointer entering its child, or moving back onto it off a nested tooltip; keyboard focus arriving in it by a key, or moving back onto it off a nested tooltip; a tap; controller.show().
  • A tooltip shown from the onHide of a tooltip with a zero animationDuration, as that tooltip is hidden by another one's show in the same registry, takes the place (#118). Both it and the tooltip whose show hid the first one stayed shown, and the registry no longer hid the second. Measured in a widget test: B, C and D in one TooltipRegistry, D with a zero fade and onHide: () => b.show(); d.show() then c.show() left B and C shown, and a later show in that registry hid only B. Now B is shown and C hides without calling onShow; C comes back when B hides, if its trigger still asks for it. The same holds when C's show turned back a fade, and an onHide there that calls c.hide() or shows D again now closes C, where C used to stay shown.

  • controller.show() on a tooltip fading out turns it back (#101). It was ignored: a fading tooltip still counts as shown, so the show returned early, while a hover re-entering the child did turn it back. A tap that closed a tooltip followed by a deferred show() left it closed. Measured in flutter_folderview: a show() deferred to a microtask from onNodeTap re-opened a closed label tooltip but not an open one.

    • The turned-back tooltip keeps its place and calls no second onShow; it re-arms showDuration. Content and hideWhenCovered still apply.
    • controller.toggle() on a fading tooltip now shows it again. A tap on a fading tooltip still hides it.
    • A tooltip turned back — by show() or by a hover — takes its registry back, so the tooltip that hid it hides. A hover used to leave both shown.
  • A tooltip rebuilt in one frame keeps its JustTooltipController (#102). When a parent key changed or a wrapper was added above it, the new tooltip attached while the old one still held the controller, which failed an assertion in debug and left show() showing nothing. Measured in flutter_folderview: switching the View Mode with per-Node controllers. A tooltip now lets go of its controller when it leaves the tree and takes it again if a GlobalKey moves it.

  • A pointer or keyboard focus that returns to the child while a waitDuration tooltip fades out brings it back at once, and it hides again when they leave (#106). It waited out waitDuration again; the fade ended during the wait, and when the wait was over the tooltip opened and stayed after the pointer left. Measured in widget tests: waitDuration 300 ms, a 200 ms fade, the pointer back 60 ms after leaving — the tooltip went off screen, came back when the wait ended, and was still shown after the pointer left. The same happened when focus returned, when the pointer left and returned after a tap closed the tooltip, when the pointer moved off a nested tooltip back onto its parent's child, and when the registry brought back a tooltip it had hidden for another one.

    • waitDuration now delays only a hidden tooltip, as in Flutter's Tooltip (see Changed above).
    • The wait a controller.show() cancels (see Changed above) used to end anyway: a tooltip the controller or the registry had hidden meanwhile opened again and stayed after the pointer left, a controller.hide() whose fade outlasted the wait was turned back, and showDuration counted from the end of the wait instead of the show. A tooltip closed while the pointer rests on its child now stays closed until the pointer leaves and returns, as after any other close.
    • Escape pressed after the pointer returned closes the tooltip. It used to do nothing while the show was waiting, and the tooltip opened when the wait ended.
  • A tooltip closed while the pointer is still on its child stays closed when the registry hides it for another tooltip during the fade-out (#117). Closed by its showDuration running out, a tap or controller.hide(), it came back as soon as the other tooltip hid, with the pointer never moving. Measured in widget tests on one TooltipRegistry: tooltip A shown by hover and closed one of those three ways, D's controller.show() 60 ms into A's fade, then d.hide() — A was shown again. Now it stays closed until the pointer leaves and returns, as after any other such close. A tooltip hidden for another one while shown, or while fading out because its trigger left, comes back as before.

    • A tooltip with animationDuration: Duration.zero whose content goes and comes back while the pointer rests on its child, or keyboard focus stays in it, shows again, as one with a fade already did. It stayed closed until the pointer left and returned.
  • A tooltip closed while the pointer or focus is still on its child stays closed when a nested tooltip, a content change or a covering route comes between during its fade-out (#126). Closed by a tap, its showDuration running out, controller.hide() or controller.toggle(), it came back with the trigger never leaving when, before the fade ended, the pointer moved onto a nested tooltip and back, its content went and came back, or a route covered it and was popped with focus still inside. Measured in widget tests, with the event 60 ms into a 200 ms fade: tooltip A shown by hover and closed by a tap, the pointer moved onto a nested tooltip and back — A was shown again; the same moves after the fade left it closed. Now it stays closed until the trigger leaves and returns, as when the same thing happens after the fade.

    • controller.hide() on a tooltip fading out because another tooltip in its registry was shown keeps it closed when that tooltip hides. d.show(); a.hide(); used to bring A back when D hid, while a.hide(); d.show(); kept it closed. A hide() after that fade has ended now keeps it closed too (#129 below).
  • A tooltip hidden by its registry for another tooltip, and then closed while the pointer or focus is still on its child, stays closed when that tooltip hides (#129). Closed by controller.hide() after the fade the registry began — even from the other tooltip's onHide — by a tap during that fade, or by its showDuration running out during it or after it, it came back as soon as the other tooltip hid, with the trigger never leaving. Measured in widget tests on one TooltipRegistry: tooltip A shown by hover and hidden by D's controller.show(), then closed one of those ways, then d.hide() — A was shown again. Now it stays closed until the trigger leaves and returns, as when the same close comes before the registry hides it.

    • A tap on it after that fade has ended still shows it at once, and the other tooltip hides. A close made after the trigger has left changes nothing, and controller.show() or the trigger returning during that fade still turns it back. A controller.hide() while a returning pointer's waitDuration runs cancels that show, as on any tooltip (#136 below).
    • A tooltip that had to wait again because yet another tooltip took the place before it came back, and was then shown by controller.show() or a tap, no longer takes a later controller.hide() or tap as such a close (#159). It stayed closed when its content went and came back with the pointer still on its child, where it showed again if the other tooltip had come after it was back.
  • controller.show() within 100 ms of the pointer or keyboard focus leaving an interactive tooltip keeps it shown (#131). The Hover Bridge, the 100 ms grace window the leave arms before hiding, was not cancelled by the show, so it hid the tooltip when it fired, whether the show found it still shown or turned back its fade. Measured in a widget test: tooltip A shown by hover, the pointer moved off, show() 40 ms later — A was gone 800 ms later, with onShow then onHide; a show() made after the bridge had fired kept it; the same after keyboard focus left. Now the shown tooltip stays until it is hidden as any tooltip the controller showed; the pointer entering and leaving it again arms the bridge as before.

  • A tooltip moved by a GlobalKey with the pointer resting on its child shows again, after its waitDuration as any hidden tooltip does (#122). The move took it down and it stayed hidden, even after the pointer moved within the child, until the pointer left and came back. Measured in a widget test: a hover-shown tooltip rebuilt inside a Padding at the same position was gone after the move and after a 1 px pointer move.

    • A tooltip closed while its trigger stays — by Escape, a tap, its showDuration or controller.hide(), even while that close is still fading out — stays closed through the move until the pointer leaves and returns. This now holds for keyboard focus too: a tooltip dismissed with Escape and moved with focus still inside came back.
    • A tooltip hidden by its registry and moved that way waits until the tooltip shown in its place hides, as #116 above.
    • A tooltip whose tap or enableTap changes in the same rebuild as its child moves from under a resting pointer hides. It stayed shown with the pointer elsewhere.
  • A nested tooltip whose enableHover is turned off while the pointer rests on it lets its outer tooltip show (#124). It kept hiding the outer one, which never showed while the pointer stayed. Measured in a widget test: the pointer on nested tooltip N inside tooltip A's child, N rebuilt with enableHover: false — N hid, and A stayed hidden. An outer tooltip hidden by its registry waits until the tooltip shown in its place hides, as #116 above.

    • A tooltip whose enableHover is turned off, and back on after the pointer has left its child, stays hidden. It used to show with the pointer elsewhere.
  • Turning enableHover off, or changing tap, forgets the pointer position a pointer-anchored tooltip had recorded, so a later controller.show() anchors at the child, as it does after the pointer leaves with hover on (#138). It anchored where the cursor was when hover was turned off, even after the pointer had gone. Measured in a widget test: a 700-wide child, the pointer at x=80, enableHover turned off, the pointer moved away, show() — the tooltip was centred at x=80 instead of the child's centre, x=350. The same held for a tap change made as the child moved from under the pointer.

    • The position is forgotten even when the pointer stays on the child, since with hover off nothing reports where it is, and a tap's position recorded before the change goes too. A tap made afterwards records its position again.
    • A TooltipTap.claim tap that is cancelled — dragged past the tap slop, or taken by another gesture — no longer leaves its position for a later controller.show(), as a TooltipTap.observe tap already did not. A tap that lands still anchors the tooltip it opens at its down position, also when enableHover changes while it is pressed.
  • controller.hide() while a hover or keyboard-focus show is still waiting out waitDuration cancels that show (#136). It did nothing, and the tooltip appeared when the wait ended. Measured in a widget test: waitDuration: 300 ms, the pointer on the child, hide() 100 ms later — the tooltip was shown at the end of the wait. Now it stays closed until the pointer or focus leaves the child and returns, as after Escape pressed during the wait.

    • A hide() with nothing shown and nothing waiting still does nothing, and a hide() on a shown tooltip still fades it out as before.
    • The same holds for the wait a tooltip hidden by its registry begins when it comes back. A controller.show() right after such a hide() opens the tooltip as it does after Escape: it stays when the pointer leaves, where it used to hide.
  • A tooltip hidden by its registry for another tooltip stays closed when its showDuration runs out while it waits out waitDuration on coming back (#143). It showed when the wait ended. Measured in a widget test: showDuration: 1 s, waitDuration: 300 ms, the pointer on the child; another tooltip's controller.show() at 400 ms, its hide() at 1100 ms; the first tooltip's showDuration ran out at 1300 ms, and it was shown at about 1440 ms. Now it stays closed until the pointer or focus leaves the child and returns, as after controller.hide() in the same wait.

    • A showDuration left over from an earlier show that runs out while the pointer or focus that has just come back waits out waitDuration still changes nothing. A tooltip with no waitDuration still comes back at once, with showDuration counted from then.
  • A tooltip hidden because its child scrolled out of sight shows again when the child is back and keyboard focus is still in it (#130). The hide was taken as a close the user made, so it stayed closed until focus left and returned. Measured in a widget test: a tooltip shown by Tab focus inside a 200 px SingleChildScrollView, scrolled by 300 and back with focus kept — shown, then hidden, and still hidden after scrolling back.

    • While its child is out of sight, the pointer and keyboard focus no longer show a tooltip; it shows once the child is visible. A tooltip hidden by its registry and brought back, one whose content returns, and one whose covering route is popped while the child is scrolled away used to show at the edge of the scroll view. Keyboard focus arriving on a child hidden by a clip that cannot scroll it into view no longer shows it at the edge either. controller.show() still shows it at the edge.
    • A tooltip closed by Escape, a tap, its showDuration or controller.hide() before its child scrolled away stays closed. Escape or controller.hide() while the child is out of sight does not close it: it shows when the child is back, as after a covering route. A tooltip opened by controller.show() stays closed when its child comes back, as after a covering route. A pointer resting over a child that scrolls away and back shows it again, as before.
  • A tooltip closed while the pointer rests on its child stays closed when a dialog is opened and closed over it, or enableHover is turned off and back on, with the pointer never moving (#127). Closed by a tap, Escape, its showDuration or controller.hide(), it came back as if the pointer had left and returned. Measured in widget tests: a TooltipTap.claim tooltip tapped closed, then a dialog pushed and popped over it — shown again; the same with enableHover turned off and on.

    • Only the pointer or keyboard focus moving away releases the close. A child scrolled from under a resting pointer and back, or rebuilt under it, leaves it closed too. The pointer moving out and back while a dialog covers the child, with the dialog then closed over it, also leaves it closed: it shows after the pointer leaves the child and returns once more.
    • A pointer that moved away while the dialog was open and enters the child after it closes shows it, as before; so does keyboard focus arriving while the pointer is elsewhere.
  • A pointer-anchored tooltip hides once its child is clipped out of sight, unless the pointer is inside the child (#144). It never hid, on the ground that a pointer inside the child proves the child shows; once the pointer had left and keyboard focus alone held the tooltip, it stayed at its anchor with its child scrolled away. Measured in a widget test: a tooltip shown by hover, focused by Tab, the pointer moved off, the child scrolled out of a 200 px scroll view — the tooltip stayed, where a child-anchored one hides. With showDuration set it also stayed when the child scrolled out from under a pointer still resting on it, until the auto-hide, and did not come back.

    • It hides as a child-anchored tooltip does, and the hide is not a dismissal: keyboard focus still inside shows it again once the child is visible, anchored afresh: at the child once the pointer has left.
    • A tooltip a touch tap opened, or one with enableHover: false, which does not track the pointer, is not held by it either: it now hides when its child is scrolled out of sight, as a child-anchored one does.
  • The pointer crossing an interactive tooltip's body pauses showDuration and resumes it on leaving, with enableHover: false too (#147). With hover off the pause had no end: a tooltip opened by a tap or by controller.show() never auto-hid again once the pointer had crossed its body. Measured in a widget test: showDuration 300 ms, controller.show(), the pointer on the body for 100 ms and off it — still shown 2 s later. The same happened when interactive was turned off with the pointer resting on the body; the countdown now restarts when the body stops taking the pointer.

  • A tooltip hides when interactive is turned off while the pointer rests on its body (#148). With no showDuration it stayed shown for good, also after the pointer left. Measured in a widget test: a tooltip shown by hover, the pointer moved from the child onto the body, then interactive: false — still shown 3 s later, and 1 s after the pointer moved away. Now it hides at once, as a non-interactive tooltip does when the pointer leaves its child, however it was shown, as the 100 ms grace window would have hidden it with interactive still on; moving the pointer back onto the child brings it back. Keyboard focus in the child still keeps it shown, and with enableHover: false nothing changes.

  • A tooltip hides when the pointer leaves its body after enableHover was turned off while the pointer rested there (#150). With no showDuration it stayed shown for good. Measured in a widget test: a tooltip shown by hover, the pointer moved from the child onto the body, enableHover: false, then the pointer moved away — still shown. Turning enableHover off changes nothing by itself; the pointer leaving the body now hides the tooltip, however it was shown, at once rather than after the 100 ms grace window. Keyboard focus in the child still keeps it shown, showDuration still restarts on leaving, and a body the pointer entered after enableHover was already off still changes nothing.

  • Setting showDuration on a tooltip already shown applies at once (#151). Set on a tooltip shown with none, it started no countdown, and once the pointer or keyboard focus left the tooltip stayed shown for good. Measured in a widget test: a tooltip shown by hover, showDuration set to 300 ms, the pointer moved away — still shown. Now a value set, or changed, while the tooltip is shown starts the countdown again from the change, however the tooltip was shown; the pointer resting on an interactive tooltip still pauses it. Cleared, the countdown stops: a tooltip whose pointer or keyboard focus had already left hides as it would have with no showDuration (when the pointer leaves the tooltip, if it rests there), and one shown by controller.show() or a tap stays until closed. A change during a fade-out, or while the tooltip is hidden, starts no countdown.

  • A hover or keyboard-focus show that waits out waitDuration follows a showDuration set or cleared during the wait (#155). The show used the value of when the wait began: set during the wait, it started no countdown, and once the pointer or keyboard focus left the tooltip stayed shown for good; cleared during the wait, the old value closed the tooltip under a pointer still resting on its child. Measured in a widget test: waitDuration 200 ms, showDuration set to 300 ms 100 ms into the wait, the pointer moved away after the show — still shown.

  • A tooltip hides when the pointer moves onto it with enableHover off just after its trigger left (#154). The pointer reaching an interactive tooltip within the 100 ms grace window cancelled the hide even with enableHover off, and leaving it then hid nothing, so the tooltip stayed shown for good. Measured in a widget test: a tooltip shown by hover, enableHover: false, the pointer moved onto the tooltip within 20 ms and away 200 ms later — still shown 2 s later; the same after keyboard focus left a tooltip with enableHover: false. Now the grace window runs out and the tooltip hides under the pointer. The pointer on the tooltip still pauses showDuration.

  • A tooltip closed with Escape while keyboard focus is inside it, then shown by controller.show(), hides after the pointer crosses its body and leaves, as it does with no focus inside (#134). Focus kept it shown for good: leaving the body did not start the 100 ms grace window while focus was anywhere inside the tooltip. Measured in a widget test on 0.5.1: Tab, Escape, show(), the pointer onto the body and away — still shown 3 s later. Now leaving the body keeps the tooltip only while keyboard focus would show it, which a dismissal, or a nested tooltip holding focus, rules out.

  • A show made while the pointer rests on an interactive tooltip's body no longer restarts showDuration (#133). The pointer on the body pauses the countdown, but the next controller.show(), or keyboard focus arriving in the child, started it again, and the tooltip hid under the pointer. Measured in a widget test: showDuration 300 ms, controller.show(), the pointer moved onto the body, then controller.show() again — gone 800 ms later. Now the countdown starts when the pointer leaves the body.

  • A hide under an opaque route calls onHide without waiting for the route to be popped (#104). An opaque route stops all animation on the route below once it has come in, so with hideWhenCovered: false a fade-out started there — by controller.hide(), showDuration, another tooltip's show, Escape, or the content going — stood still, and onHide came only after the pop. Measured in a widget test with a 2 s fade: no onHide in 4 s under the page on any of the five. A fade-out whose animation is stopped, by a route or by a TickerMode, now ends at once, so onHide runs before the call that hid it returns, as it already did with a zero animationDuration; one whose animation runs, as under a dialog, fades as before.

  • A pointer-anchored tooltip no longer anchors a later show at a tap whose show has ended (#141). On touch, and with enableHover off, a controller.show() or a keyboard-focus show anchored where the last tap on the child went down, however long ago. Measured in a widget test with tap: TooltipTap.claim and a 700-wide child: a tap at x=80 opened the tooltip, a second tap closed it, and a controller.show() 5 s later anchored at x=80 instead of the child's centre. A tap's position now lasts until the show it served ends; a later show with no pointer on the child anchors at the child. A tap that lands while the tooltip is hidden still anchors the show that follows, and a mouse resting on the child with enableHover on still anchors it at the pointer.

  • A tooltip moved by a GlobalKey together with the tooltip around it, into another tooltip's content or out of it, takes part in the registry of its new place (#119), as a tooltip moved alone already did. It kept the registry of its old place. Measured in widget tests: host H shown by its controller, tooltip A wrapping tooltip T moved into H's content, then T shown by its controller — H hid, and T with it; moved back out, T's show left a tooltip it should have hidden shown beside it.

  • A tooltip moved by a GlobalKey while its show waits out waitDuration shows when the wait ends, as if it had not moved (#139). The move cancelled the wait. A tooltip hidden by its registry, which the pointer or keyboard focus coming back was about to show, then waited until the tooltip shown in its place hid; any other tooltip started its wait again from the move. Measured in widget tests: tooltip A with a 300 ms waitDuration, hidden by D's controller.show(), the pointer out and back onto A, and 100 ms later A wrapped in a Padding at the same place — A was still hidden after 900 ms and showed only after d.hide(); not moved, it showed when the wait ended and D hid.

    • A move that also gives the tooltip another registry now shows it when the wait ends, over the tooltip shown in the new registry, as changing only the registry parameter already did (#114, #119 above).
    • A tooltip hidden by its registry whose showDuration ran out while it was hidden, then moved, stays closed when the tooltip shown in its place hides, as it does unmoved; the move used to bring it back. A revival's wait across a move runs on the same way.
    • A move with no new pointer or keyboard act still leaves a hidden tooltip waiting for the tooltip shown in its place to hide, and a move that takes the child from under the pointer still ends the wait.
  • A tooltip moved by a GlobalKey together with the tooltip around it no longer keeps hiding the tooltips it was nested in before the move (#162), as a tooltip moved alone already did not. Moved with the pointer or keyboard focus on it, it went on suppressing them, and still did after it was removed from the tree. Measured in widget tests: tooltip Z wrapping A wrapping T, the pointer on T, A moved out of Z, the pointer out and back onto Z — Z did not show; with A then removed, it still did not; and with T holding keyboard focus, Shift+Tab onto a button in Z did not show Z. A tooltip hidden by its registry that the move releases still waits for the pointer or focus to move onto it, or for the tooltip in its place to hide.

  • Escape that closes a tooltip with keyboard focus inside it is consumed, as documented, whatever the widgets around the tooltip do with Escape (#170). The tooltip closed, but the key went on unless a DismissIntent action around the tooltip consumed it; in a Scaffold one does. Measured in widget tests: under an enclosing DoNothingAction(consumesKey: false), and in a WidgetsApp with no Navigator, the press that closed a focused tooltip was reported as not handled. A tooltip shown with focus elsewhere still closes together with a dialog behind it, and a widget inside the tooltip that takes Escape itself still decides whether the key goes on.

0.5.1 #

Added #

  • A keyboard user can show and dismiss a tooltip (#92). Neither was possible: a focused child showed nothing, and no key closed a shown tooltip. Flutter's own Tooltip does neither; this follows WCAG 2.1 SC 1.4.13 (Content on Hover or Focus).

    • enableFocus: true shows the tooltip while keyboard focus is inside the child — focus that arrived by a key such as Tab, not by a click, a tap or requestFocus(). Focus may move on into the tooltip's content and keep it open. It behaves as a hover does: it waits for waitDuration, nested only the innermost tooltip shows, it needs content, and losing focus hides it. A pointer hovering an enclosing tooltip elsewhere wins. A focused tooltip hidden by another one comes back when that one hides. Off by default.
    • Escape closes the most recently shown tooltip, one per press, however it was opened, controller.show() included; with nothing shown, it cancels a show still waiting out waitDuration. A dismissed tooltip stays closed until its trigger leaves and returns — the pointer leaves the child and comes back, or focus does. A tap still opens it.
    • When focus is inside that tooltip, Escape is consumed, so a dialog behind it closes on the next press. A tooltip shown with focus elsewhere — a hover — closes along with the dialog: Flutter gives a key to both its keyboard handlers and the focused widgets, and only the second can stop it.
    • showDuration and interactive: false now say in their documentation that they leave the criterion; both defaults satisfy it.
  • A screen reader hears a tooltip (#69). The tooltip's text is put on its child's semantics node, as Flutter's Tooltip does, so TalkBack and VoiceOver read it with the child without opening anything; showing the tooltip also announces it (honoured on Android). Nothing was heard before: TooltipTap.claim only exposed a tap action, and TooltipTap.observe not even that.

    • The text is the new semanticsTooltip when given, otherwise message. A tooltipBuilder tooltip is heard only through semanticsTooltip.
    • A tooltip is heard only when it would show and its text is non-empty: an empty bubble (hideOnEmptyMessage: false) is shown and not heard, and semanticsTooltip never makes a tooltip show.
    • excludeFromSemantics: true keeps it unheard — for a child that already says what the tooltip says, such as a cell whose tooltip repeats its text.
    • Nested, only the innermost heard tooltip is heard; an outer one is silent while one inside its child is heard. Left alone, Flutter would keep the outer text and drop the inner one. An inner tooltip a screen reader cannot reach — under ExcludeSemantics, Offstage or a hidden IndexedStack child — silences it too; set excludeFromSemantics on that one (#94).
    • A screen reader still cannot open a tooltip. Under TooltipTap.observe the screen-reader tap goes to the surface around the child, as the pointer tap does; under TooltipTap.claim it opens the tooltip and the surface does not receive it, as with a pointer.

0.5.0 #

Changed #

  • Minimum Flutter is now 3.32.0 (Dart 3.8.0), up from 3.13.0 (#83). The tooltip is positioned during layout through OverlayPortal.overlayChildLayoutBuilder, so a shown tooltip follows a moving child — a scroll, a resize, an insertion above it — in the same frame. It was re-aimed after each frame and trailed by one: measured, a tooltip shown by its controller in a list scrolled 40 px per frame stood 40 px off its child on every scrolling frame.

Added #

  • tap: TooltipTap.observe — a tap trigger that does not claim the gesture (#66). enableTap puts a tap recognizer in the gesture arena, and being innermost it wins, so a tooltip on part of a tappable surface took the tap from that surface: in a folder view, a tap on a row's label opened the tooltip but never selected the row. With observe the tooltip toggles and the ancestor's tap fires.
    • The tooltip takes part in the gesture arena but never wins it: it toggles when a primary-button press is released within the touch slop (gestureSettings.touchSlop, else 18 px) and no other gesture has won by then. An ancestor's long press, drag or scroll — including a mouse drag of a few pixels — leaves the tooltip alone.
    • Gestures decided only after the release still see the tooltip toggle: under an ancestor's double tap the tooltip opens on the first tap and closes on the second, and a tap handler inside the child fires along with the tooltip.
    • Screen readers get no tap action in this mode; claim keeps the one it had.
    • Under TooltipAnchor.pointer the tooltip anchors at the tap, as it does with a claimed tap.
    • Nested, the innermost tooltip with content takes the tap, whatever mode each one uses (#68). Every tooltip that saw a tap used to toggle, and the outer one opened last and dismissed the inner one, so an inner observe tooltip lost to its ancestor. An ancestor's own tap handlers are untouched.

Fixed #

  • A tooltip inside another tooltip's content no longer closes its host (#84). Both were on the app-global registry, so showing the inner one dismissed the host, and the inner one went with the host's content — measured: hovering, tapping or touching a tooltip in a shown host's content left neither on screen. A host now gives its content a registry of its own; tooltips there are still one at a time among themselves, and an explicit registry still wins.
  • A non-interactive hover tooltip too large for either side of its target no longer flickers (#65). The clamp laid the body over the target and the pointer; the body took the pointer, the child reported an exit, the tooltip hid, the child was uncovered, and it showed again — measured in a 390-wide view with a 300-wide left/right body: shown on every other 50 ms sample. With interactive: false the body is now transparent to the pointer, as Flutter's Tooltip is for a message.
    • A tap on an interactive: false tooltip now reaches the widget beneath it, and clickable content inside such a tooltip can no longer be clicked. Use interactive: true (the default) for a tooltip with content to reach.
  • A tooltip now follows the Directionality, Theme, DefaultTextStyle and MediaQuery around it (#72). It was built in the Overlay's context, so anything set between the Overlay and the tooltip was ignored — measured: an RTL Directionality around the tooltip left a top/start body unmirrored (350–574 for a target at 350–450), a local Theme and a text scale of 2 never reached tooltipBuilder. The tooltip is now drawn through an OverlayPortal.
    • A tooltip under a local Theme, Directionality, DefaultTextStyle or MediaQuery now draws with it. If the tooltip should keep the app-level look, set those in tooltipBuilder or move the tooltip outside them.
    • A tooltip inside another tooltip's content still has no ancestor tooltips: it does not take part in nesting suppression.
  • In RTL, the arrow of a top or bottom tooltip aligned start or end now points at the target (#70). The body was mirrored but the arrow was not, so it was placed from the wrong side and pointed past the target's edge — measured on a 100 px target, 200 px tooltip: 62 px beyond it. center and the *TargetCenter alignments were unaffected.
  • A positive crossAxisOffset now moves an endTargetCenter tooltip inward, as it does for end (#73). It moved it outward — on a 100 px target with a 120 px tooltip, crossAxisOffset: 10 put the body's edge 10 px past the target's instead of 10 px inside it. The arrow still pointed at the target's centre. This includes startTargetCenter in RTL, which resolves to endTargetCenter for top and bottom.
    • A value tuned against the old direction now shifts the other way; flip its sign.

Deprecated #

  • enableTap, replaced by tap: TooltipTap.claim, which behaves identically. tap is one value with no invalid combinations; passing both is an assertion error.
    • Code still passing enableTap gets a deprecated_member_use info, which fails flutter analyze by default. Replace enableTap: x with tap: x ? TooltipTap.claim : TooltipTap.none, or TooltipTap.observe where the tooltip sits inside something tappable.

0.4.4 #

Fixed #

  • A tooltip that can never show no longer suppresses the tooltips around it (#46). With hideOnEmptyMessage (the default) an empty message means "draw nothing" — but the suppression was claimed from MouseRegion.onEnter, before that was known, so hovering such a tooltip nested inside another showed nothing at all: not the inner one, not the outer one.
    • Reachable from ordinary data. A cell tooltip whose text is '' for "no description", inside a row-level tooltip, silently kills the row's.
    • Two packages had independently grown the same local guard rather than report it, which is what a trap in the upstream default looks like.
  • A tooltip now follows its message while it is already on screen or under a resting pointer. Content that arrives makes it appear; content that leaves makes it disappear at once, bypassing showDuration as suppression already did. Previously neither was noticed until the pointer left and returned.
    • This holds however the tooltip was opened. A tooltip shown by controller.show() has no hover intent to lose, so an emptied message used to leave it standing — with the overlay now following the widget, that would have drawn an empty bubble in defiance of hideOnEmptyMessage. Showing is gated on content; hiding now is too.
  • A shown tooltip now follows its own configuration (#47). Changing message, tooltipBuilder, theme, direction or alignment while the tooltip is on screen had no effect: the overlay entry renders all of them live, but nothing ever asked it to rebuild. It now rebuilds on the next frame after any widget update.
    • A tooltipBuilder that reads mutable state at call time — (_) => Text(_message) — appeared to work, because the stale closure returned the new value. Capture the value instead and both paths were equally stale. Anyone verifying this should use the capturing form.

Changed #

  • Nesting Suppression now reads "the innermost tooltip under the pointer that has something to draw wins". Having nothing to draw is no longer enough to take an ancestor's place. hideOnEmptyMessage: false asks for the empty bubble, so such a tooltip draws, and suppresses exactly as before.

0.4.3 #

Fixed #

  • An interactive tooltip no longer dies for good when the cursor returns from the tooltip body to its child (#43). Leaving the tooltip arms the 100 ms Hover Bridge; re-entering the child did not cancel it, so it fired unseen, started a fade-out, and nothing revived it — a pointer that never left the child sends no further onEnter. The tooltip vanished about 250 ms after the cursor came home and stayed gone.
    • The reverse-catch could not help: the show request arrives while the animation is still running forward, and the reverse only begins 100 ms later, when nobody is asking to show.
    • Invisible at the moment it happens. The bridge fires while the tooltip is still on screen; it disappears 150 ms afterwards, a quarter second removed from its cause.
    • TooltipAnchor.pointer makes it easy to hit, since the tooltip is drawn beside the cursor.

0.4.2 #

Changed #

  • Minimum Flutter is now 3.13.0 (Dart 3.1.0), up from 3.10.0 (#38). The ancestor clip walk below reads RenderObject.parent, which was AbstractNode? — a type with no describeApproximatePaintClip — until Flutter 3.13.

Fixed #

  • Behaviour change. TooltipAnchor.child now targets the visible part of the child rather than its whole rect (#33). A child wider than the ancestor clipping it — a row inside a horizontal scroll viewport, say — had its tooltip aimed at a centre nobody could see. Measured: a 900px child in a 400px viewport placed its tooltip at x = 450, entirely outside the scroll view, with the cursor at x = 200.
    • screenMargin never helped: it confines the tooltip to the Overlay, usually the whole app, which an off-screen anchor satisfies.
    • A viewport reports a clip whenever clipBehavior is not Clip.none, so any JustTooltip inside a ListView or SingleChildScrollView may shift — always toward the visible part. An unclipped child is unaffected.
    • TooltipAnchor.pointer was never affected, which is why both known downstreams had independently adopted it as a workaround.
    • A child clipped away entirely — reachable only via controller.show(), since a hovering pointer proves a visible part exists — anchors at the clip edge the child lies beyond rather than refusing to show. Hiding is reserved for losing a target you had: see the tracking entry below.
  • A visible tooltip now tracks its child (#35). The target was resolved once, when the tooltip appeared, so a scroll, a resize, a layout animation, or an insertion above the child left the tooltip pointing where the child used to be. It now re-aims after any frame that moves the child, and hides once a child it was pointing at is clipped away entirely — nothing to point at, no tooltip. Hiding is a transition, not a state: controller.show() against a child that was already out of sight anchors at the clip edge rather than refusing, keeps tracking, and re-aims onto the child as soon as it scrolls into view.
  • The target rect now follows the child's paint transform. Transform.scale between the child and the Overlay previously produced a target whose origin was transformed but whose size was not, so a 2.0-scaled 100×50 child yielded a 100×50 target at the origin and a TooltipDirection.bottom tooltip drawn on top of the child instead of below it.

0.4.1 #

Added #

  • JustTooltipTheme.bare() (#30). A theme that draws no background, padding, shadow, border, or arrow — for a tooltipBuilder whose widget already draws its own surface, leaving the tooltip to contribute positioning and nothing else. Previously this meant zeroing backgroundColor, padding, and elevation by hand at every call site, where omitting any one of them silently reintroduced chrome.

0.4.0 #

Added #

  • JustTooltip.anchor and TooltipAnchor (#21). TooltipAnchor.pointer keeps the child as the hover region but anchors the tooltip at the cursor — for a child much wider than the pointer's neighbourhood (a table row, a wide card), whose centre is nowhere near where the user is looking. Defaults to TooltipAnchor.child, the existing behaviour.
    • The anchor is captured when the tooltip is shown and does not follow the pointer, so interactive tooltips stay reachable.
    • Tap-triggered tooltips anchor at the tap; a touch fires no hover events, so the tap-down supplies the position.
    • A programmatic controller.show() with no pointer present falls back to the child's rect.
    • Against a point there are no target edges to align to, so alignment says which of the tooltip's own edges lands on the pointer.

Changed #

  • Behaviour change for nested tooltips. A JustTooltip containing the pointer now suppresses every enclosing JustTooltip, regardless of registry. If you relied on a nested tooltip and its ancestor being visible together (only reachable by giving them separate TooltipRegistry instances), that no longer happens. Suppression gates hover only — a programmatic controller.show() is unaffected.

Fixed #

  • Nested JustTooltips now reliably show only the innermost tooltip under the pointer (#22). Previously this held only by coincidence — the "one tooltip at a time" registry dismissed the ancestor after it had shown — and broke in three ways:

    • an ancestor's waitDuration timer would fire while the pointer rested on a nested child, replacing the inner tooltip with the outer one;
    • moving from a nested child back onto its ancestor showed nothing at all, because the ancestor's hover region was never exited and so never re-entered;
    • tooltips scoped to separate TooltipRegistry instances showed both at once.
  • The tooltip is now positioned against its target in the coordinate space of the Overlay it is laid out in, rather than the window's (#24). The two coincide for a full-window MaterialApp, so nothing changes there — but a tooltip under a nested Navigator, an inset Overlay, or an embedded Flutter view was displaced by the Overlay's offset, and its direction flipping and screenMargin clamping were measured against the wrong bounds.

Internal #

  • Pointer facts (_pointerInside, and the pointer's last position) are now retained and a hover intent boolean derived from them, coalesced into a microtask and handed to TooltipVisibilityScheduler on transition only. This makes hover behaviour independent of Flutter's MouseTracker dispatch order. See ADR-0003. The one collaborator that must observe a hover transition synchronously — the tooltip body's onEnter, which cancels the hover bridge — flushes the pending recomputation first.
  • TooltipVisibilityScheduler and TooltipRegistry are unchanged.
  • JustTooltipPositionDelegate.targetRect is documented as being in the Overlay's coordinate space; the child rect and the pointer anchor both arrive in it.
  • A second example entry point (example/lib/spike_wide_row.dart) exercises pointer anchoring, nested suppression, an inset Overlay and an interactive tooltip together.
  • Test coverage: 125 tests. Every test added this release was mutation-checked — reverting the code it covers must make it fail.

0.3.0 #

Breaking #

  • JustTooltipController is no longer a ChangeNotifier. It is now an attach-based command source (modeled on Flutter's OverlayPortalController): show()/hide()/toggle() drive the attached tooltip, which is the single source of truth for visibility.
    • removed the shouldShow getter — use isShowing (reflects the tooltip's live state) instead
    • removed addListener/removeListener/dispose (ChangeNotifier API) — observe visibility via the widget's onShow/onHide callbacks
    • removed the internal resetShouldShow()
  • Narrowed the public API — JustTooltipPositionDelegate, TooltipShapePainter, and JustTooltipOverlay are no longer exported (they are internal implementation details). The public surface is now JustTooltip, JustTooltipController, JustTooltipTheme, TooltipRegistry, and the enums.

Added #

  • An optional registry parameter and TooltipRegistry class to scope the "one tooltip visible at a time" policy — pass a shared TooltipRegistry() to a group of tooltips to isolate them (or a test); omitting it keeps the app-global default.

Fixed #

  • controller.show() called before the JustTooltip mounts is now honoured (the queued show is applied once mounted); previously it was ignored.
  • slide and fadeSlide animations now enter from the auto-flipped (resolved) direction — a tooltip that flips (e.g. top → bottom near a screen edge) slides in from the side it actually appears on, not the originally-requested one.

Internal #

  • Extracted the hover/auto-hide timing into a dedicated TooltipVisibilityScheduler (timer cancellation collapsed into one place).
  • Extracted the 7 show/hide animations into a dedicated TooltipTransitions module.
  • Moved the single-visible-tooltip policy out of a static Set into the injectable TooltipRegistry.
  • Test coverage raised to ~97% (scheduler, transitions, registry, controller, painter, and hover integration).

0.2.5 #

  • feat add TooltipAlignment.startTargetCenter and endTargetCenter alignments where the arrow dynamically points to the center of the target widget
  • example add Top-StartTarget and Top-EndTarget quick presets to playground

0.2.4 #

  • feat add hideOnEmptyMessage parameter to suppress tooltip when message is empty (default: true)
  • example add hideOnEmptyMessage toggle to Content section in playground

0.2.3 #

  • fix borderColor not visible on non-arrow tooltips (showArrow: false) due to Material background covering DecoratedBox border

0.2.2 #

  • fix rename TooltipPositionDelegate → JustTooltipPositionDelegate to resolve name conflict with Flutter SDK's TooltipPositionDelegate (introduced in Flutter 3.32)

0.2.1 #

  • feat add TooltipAnimation enum with 7 animation types: none, fade, scale, slide, fadeScale, fadeSlide, rotation
  • feat add animation and animationCurve parameters for animation type and curve selection
  • feat add fadeBegin, scaleBegin, slideOffset, rotationBegin parameters for fine-tuning animations
  • docs add Animation section to README with usage examples and API reference
  • example add Animation section with type/curve dropdowns and parameter sliders

0.2.0 #

  • BREAKING extract 12 visual styling parameters into JustTooltipTheme class
    • backgroundColor, borderRadius, padding, elevation, boxShadow, borderColor, borderWidth, textStyle, showArrow, arrowBaseWidth, arrowLength, arrowPositionRatio are now accessed via theme parameter
    • Migration: wrap style params in theme: JustTooltipTheme(...)
  • feat add JustTooltipTheme.copyWith() for easy theme derivation
  • feat JustTooltipTheme is a reusable data class with == / hashCode support

0.1.7 #

  • fix controller show() not working after tooltip was dismissed by hover-out or auto-hide

0.1.6 #

  • feat add showArrow parameter with unified path rendering (arrow integrated into tooltip shape)
  • feat add arrowBaseWidth and arrowLength parameters for arrow size customization
  • feat add arrowPositionRatio parameter to control arrow placement along the tooltip edge
  • feat add borderColor and borderWidth parameters for tooltip outline (follows arrow shape)
  • feat arrow auto-flips with tooltip direction when viewport space is insufficient
  • fix tooltip not reappearing when re-hovering during fade-out animation

0.1.5 #

  • feat add viewport overflow protection with auto direction flip and position clamping
  • feat add screenMargin parameter to control minimum distance from screen edges
  • docs tooltipBuilder now documents that content sizing is the caller's responsibility

0.1.4 #

  • fix interactive mode now properly pauses auto-hide timer while cursor is on tooltip

0.1.3 #

  • feat add boxShadow parameter for custom shadow control (color, blur, spread, offset)

0.1.2 #

  • feat add interactive option to control whether tooltip stays visible on hover
  • feat add waitDuration for delayed tooltip appearance on hover
  • feat add showDuration for auto-hiding tooltip after a set time with timer reset on re-enter

0.1.1 #

  • feat add crossAxisOffset parameter for shifting tooltip along the cross-axis

0.1.0 #

  • implement JustTooltip core widget with direction (top/bottom/left/right) + alignment (start/center/end)
  • implement JustTooltipController for programmatic show/hide/toggle
  • implement tooltip position utils with 12-combination anchor mapping and RTL support
  • feat hover and tap trigger modes
  • feat fade animation with configurable duration
  • feat custom tooltip content via tooltipBuilder
  • feat single-instance enforcement (only one tooltip visible at a time)
  • feat interactive playground example app with theme switching
3
likes
150
points
1.87k
downloads

Documentation

API reference

Publisher

verified publisherkihyun1998.com

Weekly Downloads

A lightweight, customizable Flutter tooltip with flexible placement, hover, tap & keyboard triggers, screen-reader support, programmatic control, and RTL support.

Repository (GitHub)
View/report issues

Topics

#tooltip #overlay #popup #widget #ui

License

MIT (license)

Dependencies

flutter, meta

More

Packages that depend on just_tooltip