tooltip

tooltip displays additional information when users hover over or focus a component.

XML Element

tooltip

Java Class

Tooltip

Basics

LIVE DEMO

tooltip is a nested element of almost all components and layouts.

To add a nested tooltip element in Jmix Studio, select the UI element in the view descriptor XML or in the Jmix UI structure panel and click on the Add→Tooltip button in the Jmix UI inspector panel.

An example of defining a textField with a tooltip:

<textField label="Field with tooltip">
    <tooltip text="Tooltip text"/>
</textField>

Programmatic Definition

The tooltip component can be defined programmatically within your application code. Here’s an example of how you can define and use tooltip programmatically for the textField component:

@ViewComponent
private TypedTextField<String> programmaticField;

@Subscribe
public void onInit(final InitEvent event) {
    programmaticField.setTooltipText("This is a tooltip")
            .setPosition(Tooltip.TooltipPosition.START);
}

Positioning

LIVE DEMO

tooltip, by default, positions itself relative to the target component it’s attached to. It automatically calculates the best location for the tooltip to appear, taking into account the available space on the screen and avoiding overlaps with other elements.

The position attribute directly affects the tooltip’s location on the screen, allowing you to control where the tooltip appears. The position attribute accepts values from the TooltipPosition enumeration.

You can set the position attribute using the setPosition() method in your code:

@ViewComponent
protected JmixSelect<Tooltip.TooltipPosition> position;
protected void initPositionItems() {
    ComponentUtils.setItemsMap(position, getPositionItemsMap());
    position.setValue(Tooltip.TooltipPosition.TOP);
}
@Subscribe("position")
protected void onPositionChange(
        ComponentValueChangeEvent<JmixSelect<Tooltip.TooltipPosition>, Tooltip.TooltipPosition> event) {
    customTooltipField.getTooltip().setPosition(event.getValue());
}
protected Map<Tooltip.TooltipPosition, String> getPositionItemsMap() {
    return Arrays.stream(Tooltip.TooltipPosition.values())
            .collect(Collectors.toMap(Function.identity(),mode -> mode.name().replace('_', ' ')));
}

In the view descriptor XML, you can specify the position attribute:

<select id="position" label="Position"/>

Configuring Delays

LIVE DEMO

tooltip provides the ability to configure delays for its appearance and disappearance, allowing you to control the timing of the tooltip’s interaction with the user.

Focus Delay

The focusDelay attribute controls the delay, in milliseconds, before the tooltip appears when the mouse hovers over the component with the tooltip element.

In this example, the tooltip will appear after a 500-millisecond delay when the mouse hovers over the text field:

@Subscribe("focusDelay")
protected void onFocusDelayChange(ComponentValueChangeEvent<IntegerField, Integer> event) {
    Integer value = event.getValue();

    if (value != null && value > 0 && value <= 5000) {
        customTooltipField.getTooltip().setFocusDelay(value);
    } else {
        customTooltipField.getTooltip().setFocusDelay(0);
    }
}

Hide Delay

The hideDelay attribute controls the delay, in milliseconds, before the tooltip hides when the mouse leaves the component with the tooltip element.

In this example, the tooltip will remain visible for 1 second after the mouse leaves the text field before disappearing:

@Subscribe("hideDelay")
protected void onHideDelayChange(ComponentValueChangeEvent<IntegerField, Integer> event) {
    Integer value = event.getValue();

    if (value != null && value > 0 && value <= 5000) {
        customTooltipField.getTooltip().setHideDelay(value);
    } else {
        customTooltipField.getTooltip().setHideDelay(0);
    }
}

Hover Delay

The hoverDelay attribute controls the delay, in milliseconds, before the tooltip appears when the mouse hovers over the component with the tooltip element.

In this example, the tooltip will appear after a 500-millisecond delay when the mouse hovers over the text field:

@Subscribe("hoverDelay")
protected void onHoverDelayChange(ComponentValueChangeEvent<IntegerField, Integer> event) {
    Integer value = event.getValue();

    if (value != null && value > 0 && value <= 5000) {
        customTooltipField.getTooltip().setHoverDelay(value);
    } else {
        customTooltipField.getTooltip().setHoverDelay(0);
    }
}

Triggering Manually

LIVE DEMO

You can configure tooltips to appear programmatically, meaning they won’t show on hover or focus, but only when triggered by your code. This is particularly useful when:

  • You need to display the tooltip based on specific conditions or user interactions.

  • The tooltip content needs to be dynamically generated or updated.

In the view descriptor XML, set the manual attribute to true. This indicates that the tooltip will not be displayed automatically and requires manual control.

<textField id="manualTooltipField" label="Manual tooltip">
    <tooltip text="Tooltip text" manual="true" position="END_BOTTOM"/>
</textField>

Then configure the tooltip within the view controller.

@ViewComponent
protected TypedTextField<String> manualTooltipField;
@Autowired
protected UiComponents uiComponents;
@Subscribe
protected void onInit(InitEvent event) {
    initManualTooltip();
    initPositionItems();
}
protected void initManualTooltip() {
    JmixButton helperButton = createHelperButton();
    Tooltip tooltip = manualTooltipField.getTooltip();
    helperButton.addClickListener(e -> tooltip.setOpened(!tooltip.isOpened()));

    manualTooltipField.setSuffixComponent(helperButton);
}
protected JmixButton createHelperButton() {
    JmixButton helperButton = uiComponents.create(JmixButton.class);
    helperButton.setIcon(VaadinIcon.QUESTION_CIRCLE.create());
    helperButton.addThemeVariants(ButtonVariant.LUMO_ICON);
    helperButton.addClassName(StyleUtility.Button.LINK_BUTTON);

    return helperButton;
}

The opened attribute controls whether the tooltip is currently visible. It’s a boolean value, with true indicating the tooltip is open and false indicating it’s closed.

While opened can be set manually, it’s typically managed by the framework itself based on events such as mouse hover or focus. The attribute is useful for controlling tooltip visibility in scenarios where you need to programmatically open or close it.

Attributes

The following attributes are specific to tooltip:

Name Description Default

focusDelay

Defines the delay in milliseconds before the tooltip is opened on keyboard focus, when not in manual mode. See Focus Delay.

0

hideDelay

Defines the delay in milliseconds before the tooltip is closed on losing hover, when not in manual mode. On blur, the tooltip is closed immediately. See Hide Delay.

0

hoverDelay

Defines the delay in milliseconds before the tooltip is opened on hover, when not in manual mode. See Hover Delay.

0

manual

When true, the tooltip is controlled programmatically instead of reacting to focus and mouse events. See Triggering Manually.

false

opened

When true, the tooltip is opened programmatically. Only works if manual is set to true. See Triggering Manually.

false

position

Defines the position of the tooltip with respect to its target. See Positioning.

—

text

Defines the string used as a tooltip content.

—

See Also