Skip to content
BlazorUI

Surfaces

Tooltip

Bit.BlazorUITipHint

Tooltip briefly describes an unlabeled control or adds a bit of information to a labeled one. It is shown on hover, focus or a press of its anchor, on any side of it and lined up along that side, with an arrow, stays while the pointer moves into it, is dismissed by Escape, names or describes its anchor to screen readers, and shares its delays across a group.

Notes

The tooltip is placed purely in CSS, inside the flow of the page next to its anchor. So an ancestor with overflow: hidden clips it, and it stays on the side it is given instead of flipping to one with room. For a surface that has to escape an overflow, find its own room or hold controls, use BitCallout.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

Whatever is inside the tooltip is its anchor; Text is what it says. It is shown on hover and on focus. Disabled turns the tooltip off, not the anchor, and a disabled anchor still gets its tooltip. DefaultIsShown starts it shown.

Placement & alignment

Placement puts the tooltip on one of the four sides of the anchor, and Alignment centers it there or lines it up with either end. Start and End follow the reading direction.

Triggers

ShowOnHover and ShowOnFocus (both on by default) pick what shows the tooltip. ShowOnClick makes a press of the anchor toggle it; HideOnClick hides a hover tooltip on the press. Enter and Space count as a press.
On touch, a tap shows the tooltip for TouchHideDelay ms; TouchShowDelay turns it into a long press and NoTouch ignores touch altogether.

Delay & group

ShowDelay waits before showing (pointer only - the keyboard gets it at once) and HideDelay before hiding.
BitTooltipGroup hands its delays to the tooltips inside that set none, shows one at a time (unless AllowMultiple), and skips the show delay for SkipDelay ms after one hides. Rest on Bold, then move along.


Arrow, offset & width

HideArrow drops the arrow and ArrowSize resizes it. Offset is the gap to the anchor, never less than the arrow needs. MaxWidth is where the text wraps (none removes the cap), and FullWidth keeps a block-level anchor as wide as its container.

Interactive

A tooltip is hoverable by default: the pointer can move into it, to read or select its text, without it hiding (WCAG 1.4.13). Interactive="false" lets the pointer through to what lies underneath and hides it on leaving the anchor.

Template

Template holds any content, and Anchor is an alias of ChildContent. LazyRender keeps the content out of the DOM until the first show: its stamp below is taken on your first hover, the other one's on page load.

Accessibility

Relationship is what the tooltip is to its anchor: Description (default, aria-describedby), Label (aria-labelledby, for an icon-only button) or None. It is copied onto the first focusable control inside, unless that control sets its own; TooltipId is the id to point at by hand.
Escape dismisses a shown tooltip - with the focus on the anchor, or anywhere while the pointer rests on it - without also closing a dialog around it. NoDismissOnEscape turns that off. A field or a dropdown inside the anchor still gets its own Escape.

Binding & methods

@bind-IsShown keeps the state in your field while the triggers still work. IsShown without the binding makes the state yours alone. Show, Hide and Toggle act at once, ignoring triggers and delays.

Events

OnShow, OnHide and OnToggle fire once the state has actually changed, never for a cancelled trigger.

Cascading parameters

BitParams hands a BitTooltipParams to every tooltip under it, so a toolbar sets its tooltips up once. They are defaults: a tooltip's own parameter wins, and so does a BitTooltipGroup's delay. Text, content and state stay per tooltip.

Color

Color paints the surface and the arrow, with a text color that stays legible in every theme.

Size

Size sets the text size and the padding. Unset, a tooltip is as small as Small.

Style & Class

Style and Class reach the root; Styles and Classes reach the root, the wrapper, the surface and the arrow. NoAnimation drops the fade, and ZIndex lifts the surface over a neighbour painted above it.


CSS variables inherit: set one on :root for every tooltip, on an ancestor for a region, or on a tooltip's Style. A parameter set on the tooltip wins.

RTL

Dir lays the tooltip out right to left. For both Placement and Alignment, Start and End follow the reading direction, so Start is the right here, while Left and Right name screen sides and stay put.

CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle that one alone. Leave a variable unset and the component falls back to the theme token beside it.

BitTooltip CSS variables

Name Default value Description
--bit-Tooltip-background --bit-clr-tooltip-bg Fill of the surface and the arrow. The Color parameter wins over it.
--bit-Tooltip-color --bit-clr-tooltip-fg Text color. The Color parameter wins over it.
--bit-Tooltip-padding spacing(1.25) Room around the content. The Size parameter wins over it.
--bit-Tooltip-font-size --bit-tpg-fs-xs Size of the text. The Size parameter wins over it.
--bit-Tooltip-font-weight --bit-tpg-fw-medium Weight of the text.
--bit-Tooltip-line-height --bit-tpg-caption1-line-height Height of a line of text, as a ratio of the font size so it follows Size.
--bit-Tooltip-text-align start Alignment of a text that wraps onto more than one line.
--bit-Tooltip-radius --bit-shp-radius-popup Corner of the surface.
--bit-Tooltip-shadow --bit-shd-tooltip Elevation of the surface and the arrow.
--bit-Tooltip-max-width 20rem Width the text wraps at. The MaxWidth parameter wins over it.
--bit-Tooltip-offset spacing(1.25) Distance from the anchor, never less than the arrow needs. The Offset parameter wins over it.
--bit-Tooltip-arrow-size spacing(1.5) Side of the square the arrow is drawn from. The ArrowSize parameter wins over it.
--bit-Tooltip-z-index --bit-zin-callout Stacking order of the surface and the arrow. The ZIndex parameter wins over it.

API

Every parameter, public member, sub-class and enum this component exposes.

BitTooltip parameters

Name Type Default value Description
Alignment BitPlacement BitPlacement.Center Where along Placement the tooltip lines up with its anchor: an edge value puts the tooltip's edge on the same edge of the anchor and lets it grow away from there, as BitCallout does. Start, Center and End are honoured on either axis (Start and End follow the reading direction across, and read top to bottom down); Left and Right only above or below the anchor, Top and Bottom only beside it. Anything else centers it.
Anchor RenderFragment? null Alias of ChildContent: the anchor the tooltip belongs to.
ArrowSize int? null The side in pixels of the square the arrow is drawn from. Unset keeps the theme's size.
ChildContent RenderFragment? null The anchor the tooltip belongs to and is shown next to.
Classes BitTooltipClassStyles? null Custom CSS classes for different parts of the tooltip.
Color BitColor? null The general color of the tooltip surface and its arrow.
DefaultIsShown bool? null The shown state the tooltip starts in when IsShown is not bound.
FullWidth bool false Stretches the element the anchor is wrapped in to the full width, so a block-level anchor keeps its width.
HideArrow bool false Hides the arrow.
HideDelay int 0 Delay in ms before hiding. Inside a BitTooltipGroup an unset one takes the group's.
HideOnClick bool false Hides the tooltip when the anchor is pressed (pointer, Enter or Space). ShowOnClick takes the press over.
Interactive bool true Keeps the tooltip shown while the pointer moves into it (WCAG 1.4.13). False lets the pointer through to what lies underneath.
IsShown bool false The shown state of the tooltip. Bound one way (without IsShownChanged) it is yours alone: the triggers leave it alone.
IsShownChanged EventCallback<bool> The callback for when the shown state changes.
LazyRender bool false Keeps the content out of the DOM until the first show. The accessible text is only there from then on.
MaxWidth string? null The CSS width the text wraps at; "none" removes the cap. Unset keeps the theme's.
NoAnimation bool false Removes the fade the tooltip is shown and hidden with.
NoDismissOnEscape bool false Keeps Escape from dismissing the tooltip. Only for a tooltip that covers nothing (WCAG 1.4.13).
NoTouch bool false Ignores touch and pen, leaving the tap to the anchor.
Offset int? null The gap in pixels between the anchor and the tooltip, never less than the arrow needs. Unset keeps the theme's.
OnHide EventCallback The callback for when the tooltip is hidden.
OnShow EventCallback The callback for when the tooltip is shown.
OnToggle EventCallback<bool> The callback for when the tooltip is shown or hidden, with the new state.
Placement BitPlacement BitPlacement.Top The side of the anchor the tooltip is placed on. Only Top, Bottom, Start, End, Left and Right are honoured: Start and End follow the reading direction, Left and Right stay on the same side of the screen. Anything else leaves it above the anchor.
Relationship BitTooltipRelationship BitTooltipRelationship.Description Whether the tooltip describes (aria-describedby), names (aria-labelledby) or is hidden from its anchor. Copied onto the first focusable control inside.
ShowDelay int 0 Delay in ms before showing on hover; focus and click show at once. Inside a BitTooltipGroup an unset one takes the group's.
ShowOnClick bool false Makes a press of the anchor (pointer, Enter or Space) toggle the tooltip. Escape, a press outside and Tab also hide it.
ShowOnFocus bool true Shows the tooltip when the anchor takes the keyboard focus. A focus from a pointer press is left to the pointer.
ShowOnHover bool true Shows the tooltip while the pointer is over the anchor.
Size BitSize? null The size of the text and the padding.
Styles BitTooltipClassStyles? null Custom CSS styles for different parts of the tooltip.
Template RenderFragment? null The content of the tooltip, in place of Text.
Text string? null The text of the tooltip.
TouchHideDelay int 1500 How long in ms a tooltip shown by a touch stays. Zero keeps it until something else hides it.
TouchShowDelay int 0 How long in ms a touch has to rest on the anchor before the tooltip shows, making it a long press.
ZIndex int? null The stacking order of the surface and its arrow. Unset keeps the theme's popup layer.

BitTooltip public members

Name Type Default value Description
Show Task Shows the tooltip programmatically, at once and regardless of the triggers it is configured with, unless it is disabled.
Hide Task Hides the tooltip programmatically, at once and regardless of the delays it is configured with.
Toggle Task Shows the tooltip if it is hidden and hides it if it is shown.
TooltipId string The id of the element the text of the tooltip is rendered in, which is what an anchor of your own points its aria-describedby or aria-labelledby at.

BitComponentBase parameters

Name Type Default value Description
AriaLabel string? null Gets or sets the accessible label for the component, used by assistive technologies.
Class string? null Gets or sets the CSS class name(s) to apply to the rendered element.
Dir BitDir? null Gets or sets the text directionality for the component's content.
Disabled bool false Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction.
ForceAnimation bool false Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested.
HtmlAttributes Dictionary<string, object> new Dictionary<string, object>() Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters.
Id string? null Gets or sets the unique identifier for the component's root element.
Style string? null Gets or sets the CSS style string to apply to the rendered element.
TabIndex string? null Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility BitVisibility BitVisibility.Visible Gets or sets the visibility state (visible, hidden, or collapsed) of the component.

BitComponentBase public members

Name Type Default value Description
UniqueId Guid Guid.NewGuid() Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement ElementReference Gets the reference to the root HTML element associated with this component.

BitTooltipGroup properties

Groups the tooltips inside it: they share its delays, show one at a time, and skip the show delay right after one hides. It renders nothing of its own.

Name Type Default value Description
AllowMultiple bool false Lets more than one tooltip of the group be shown at a time.
ChildContent RenderFragment? null The tooltips the group is around.
HideDelay int? null The delay in milliseconds before hiding, for every tooltip in the group that does not set one of its own.
ShowDelay int? null The delay in milliseconds before showing, for every tooltip in the group that does not set one of its own.
SkipDelay int 300 How long in ms after a tooltip of the group hides the next one is shown without its show delay. Zero turns it off.

BitTooltipClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitTooltip.
TooltipWrapper string? null Custom CSS classes/styles for the tooltip wrapper of the BitTooltip.
Tooltip string? null Custom CSS classes/styles for the tooltip of the BitTooltip.
Arrow string? null Custom CSS classes/styles for the arrow of the BitTooltip.

BitPlacement enum

Name Value Description
Top 0 The top edge.
Bottom 1 The bottom edge.
Start 2 The edge the reading direction starts from - the left in LTR, the right in RTL. On the vertical axis, which does not turn around, it is the top.
End 3 The edge the reading direction ends at - the right in LTR, the left in RTL. On the vertical axis, which does not turn around, it is the bottom.
Left 4 The left edge, in both reading directions.
Right 5 The right edge, in both reading directions.
Center 6 The middle of the axis, against neither edge.
TopAndBottom 7 Both edges of the block axis at once.
StartAndEnd 8 Both edges of the inline axis at once, following the reading direction the way Start and End do.

BitTooltipRelationship enum

Name Value Description
Description 0 The tooltip adds information to an anchor that already has a name of its own, and is pointed at with aria-describedby.
Label 1 The tooltip is the name of an anchor that has none of its own - an icon-only button, above all - and is pointed at with aria-labelledby.
None 2 The tooltip is left out of the accessibility tree altogether, for the case where the anchor already carries the same text by another route.

BitColor enum

Name Value Description
Primary 0 Primary general color.
Secondary 1 Secondary general color.
Tertiary 2 Tertiary general color.
Info 3 Info general color.
Success 4 Success general color.
Warning 5 Warning general color.
SevereWarning 6 SevereWarning general color.
Error 7 Error general color.
PrimaryBackground 8 Primary background color.
SecondaryBackground 9 Secondary background color.
TertiaryBackground 10 Tertiary background color.
PrimaryForeground 11 Primary foreground color.
SecondaryForeground 12 Secondary foreground color.
TertiaryForeground 13 Tertiary foreground color.
PrimaryBorder 14 Primary border color.
SecondaryBorder 15 Secondary border color.
TertiaryBorder 16 Tertiary border color.

BitSize enum

Name Value Description
Small 0 The small size tooltip.
Medium 1 The medium size tooltip.
Large 2 The large size tooltip.

BitVisibility enum

Name Value Description
Visible 0 The content of the component is visible.
Hidden 1 The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed 2 The component is hidden (display:none).

BitDir enum

Name Value Description
Ltr 0 Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl 1 Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto 2 Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.