Tooltip

Text is what the tooltip says, and whatever is put inside the tooltip is the anchor it belongs to and is shown next to. Out of the box the tooltip is shown when the pointer enters the anchor and when the keyboard reaches it, and is hidden again when both of them have left. IsEnabled turns the tooltip off without touching the anchor, and hides one that is already shown. A tooltip left without a text and without a template is no tooltip at all: no surface is put on the page for it and nothing points at it. Because the tooltip listens on the element it wraps the anchor in rather than on the anchor itself, a disabled control - which answers no pointer of its own - still has a tooltip that explains why it is disabled.

Position is the place the tooltip takes around its anchor: one of the four sides, each of them also available lined up with either end of the anchor rather than centred on it. The arrow follows the tooltip and keeps pointing back at the anchor from wherever it lands. All twelve are shown open here at once; they are the same tooltip in every other respect.

Switches decide what shows the tooltip and what takes it away. ShowOnHover (on by default) answers the pointer entering the anchor and ShowOnFocus (on by default as well) answers the keyboard reaching it; the two are kept apart, so a pointer leaving an anchor the keyboard is still on does not take the tooltip away with it, and a click that focuses the anchor is not mistaken for a tab that reached it. ShowOnClick turns the anchor into a toggle, and HideOnClick instead has an ordinary hover tooltip step aside the moment the anchor is pressed, which is what a button that opens something else owes the reader. Both of them answer the keyboard the way they answer the pointer: Enter and Space on the anchor are a press of it, so a click-driven tooltip can be opened without a pointer at all. A tooltip opened that way stays until the anchor is pressed again, Escape is pressed on it, or the focus leaves it - which a click elsewhere on the page and a Tab away from it both come down to. On a touch screen there is no pointer that hovers, so a tap shows the tooltip and it hides itself again after TouchHideDelay milliseconds; TouchShowDelay makes the tooltip a long press of its own, so that a tap that only meant to press the anchor leaves it out of it, and NoTouch leaves the touch to the anchor altogether.

ShowDelay is how long the pointer has to rest on the anchor before the tooltip is shown, which keeps a pointer merely crossing a row of controls from lighting all of them up. HideDelay is how long the tooltip stays behind once the pointer has left, which stops it flickering when the pointer slips off an edge and comes back. Both are cancelled by the opposite move arriving first, and the show delay is for the pointer alone: a tooltip reached with the keyboard or opened by a click is shown at once, since it was asked for.

BitTooltipGroup makes a row of tooltips behave as the one piece of chrome a reader takes them for. It hands its ShowDelay and HideDelay to every tooltip inside it that does not set one of its own, keeps only one of them on the screen at a time (unless AllowMultiple says otherwise), and drops the show delay for SkipDelay milliseconds after one of them has been hidden - once the reader has stopped to read the first tooltip they are reading the row rather than crossing it, and waiting again only reads as lag. Rest on the first button below, then walk along the rest of them.

The arrow points from the tooltip back at the anchor. HideArrow leaves it out, ArrowSize sets the length of the side of the square it is drawn from, and Offset is the distance in pixels the tooltip is held off the anchor, which is also the room the arrow is drawn in - an arrow that reaches further than that is given the room it needs anyway. Leaving the last two unset keeps whatever the theme gives them.

Interactive lets the pointer travel into the tooltip and rest there without it being hidden, which is what WCAG 1.4.13 asks of anything shown on hover and what a tooltip whose text has to be read across, magnified or selected needs. The gap between the anchor and the tooltip is bridged, so the pointer never leaves the component on the way over, and a pointer released inside the tooltip is not taken for a click on the anchor. A tooltip that holds something to click or to type in is a callout rather than a tooltip: it has to take the focus, which a tooltip never does.

Template is the content of the tooltip when a plain Text is not enough, and Anchor (an alias of ChildContent) is what it belongs to. Both are ordinary render fragments, so anything may go in them - the tooltip is sized to what it holds.

A tooltip is only as wide as what it holds, up to a cap the theme sets, past which the text wraps onto another line instead of the tooltip running on across the screen. MaxWidth takes any CSS length to set that cap yourself, and the value "none" takes it off for the tooltip that is meant to be a single line however long it is.

The Escape key hides the tooltip while the keyboard is on the anchor, without the focus having to move away first - the "dismissible" half of WCAG 1.4.13, and what a tooltip that covers what is underneath it owes the reader. It stays dismissed until the anchor is left and reached again, rather than coming straight back. NoDismissOnEscape turns that off, which is only for a tooltip that obscures nothing. Tab to either of these and press Escape. A tooltip a press of the anchor opened is dismissed by the focus leaving it as well, since a click somewhere else on the page and a Tab away from the anchor both take the focus off it - a pointer still resting on the anchor keeps it, having asked for it in its own right.

Relationship says what the tooltip is to its anchor. Description, the default, points an aria-describedby at it, which is the tooltip that adds something to a control that already has a name. Label points an aria-labelledby at it instead, for the icon-only button whose only name the tooltip is. None leaves it out of the accessibility tree, for the tooltip that only repeats what the anchor already says. The relationship is declared for as long as there is a tooltip to declare it with, not only while it is on the screen, so a screen reader has the text the moment the anchor is reached. A description is computed on the element that has the focus, and the element the tooltip declares the relationship on is the container it wraps the anchor in, so the same relationship is copied onto the first focusable control inside that container - the button the reader actually lands on. An anchor that names a description or a label of its own keeps it. TooltipId is the id of the element the text lands in: point an anchor of your own at it where there is nothing focusable for the copy to land on, or where something other than the first control is what the tooltip belongs to.

LazyRender keeps the content of the tooltip out of the DOM until the tooltip is first shown, and keeps it rendered from then on, so a page carrying many tooltips over costly content is not paying for all of them up front. The timestamp below is taken while the content renders: the lazy one is stamped the moment you first hover it, the other one the moment the page loaded.

DefaultIsShown is the state the tooltip starts in and then manages itself. @bind-IsShown hands that state to your own field instead: the tooltip keeps answering its triggers and reports every change back, so the two stay in step. Handing IsShown over without binding it makes the state entirely yours - the triggers are then left alone and only your code shows and hides the tooltip.

A reference to the component gives you Show, Hide and Toggle, which act at once and regardless of the triggers and the delays the tooltip is configured with. They are what a tooltip driven by something happening elsewhere on the page needs - a validation that has just failed, a step of a tour - rather than by the pointer on its anchor.

OnShow and OnHide report the tooltip changing state, and OnToggle reports both of them with the new state, so a single handler can follow the tooltip. They are called once the delays have run out and the state has actually changed, never for a trigger that was cancelled before it landed.

Everything above on one tooltip, to try the combinations out on.

Color paints the surface of the tooltip and the arrow along with it, out of the same palette the rest of the library reads, so the text on it stays legible in every theme. The eight semantic colors carry a meaning worth spending on a tooltip - an error, a warning, a confirmation - and the neutral background, foreground and border families are there for a tooltip that has to sit against a particular surface.

Size moves the tooltip along the type ramp the library shares and pads it to match. A tooltip is small chrome by nature, so the one you do not size sits at the small end of that ramp already; Medium and Large are for the tooltip whose text is the point rather than a footnote.

Style and Class reach the root element, and Styles and Classes reach the parts inside it - the root, the wrapper the tooltip is placed by, the tooltip surface itself and the arrow - so a single tooltip can be reshaped without a rule that catches every other one on the page. NoAnimation takes the fade off, for a tooltip that should simply be there, and ZIndex lifts the surface over a neighbour that the page would otherwise paint on top of it - the tooltip is stacked inside the flow of the page rather than at the end of the body. FullWidth is for the block-level anchor: the tooltip wraps what it belongs to in an element laid out inline, which would otherwise shrink a text field or a stretched button to the width of its own content.

Set Dir to Rtl to lay the content of the tooltip out right-to-left. The positions are named for the sides of the screen rather than for the reading order, so Left is the left of the anchor in either direction. MirrorInRtl swaps the two sides while the direction is right-to-left, so that a tooltip meant to follow the text - a hint beside a field, say - lands on the side the reader starts at; leave it off for one that has to stay where it is put.