Tooltips

import {enableTooltips} from 'cx/widgets';

Tooltips provide additional information regarding the element under the mouse pointer. In Cx, tooltips are used as a default way to display validation errors on form fields.

To enable tooltips execute the enableTooltips method at startup of your application. Tooltips are not automatically enabled to preserve small bundle sizes for applications where they are not needed.

Basic

Displayed on top!

Title

Rich content

Component inside

Always visible

Controlled visibility

Mouse tracking

Touch devices do not offer precise mouse pointer location, so tooltips are shown/hidden when the user taps the element containing the tooltip. Sometimes, this is not the desired behavior and you can make tooltips to ignore touch events, by setting touchBehavior to ignore.

To make all tooltips ignore touch events by default, set Tooltip.prototype.touchBehavior = 'ignore';.

Controller Index

import {enableTooltips} from "cx/widgets";
enableTooltips();

<div class="widgets" controller={PageController}>
    <div tooltip="This is a tooltip." style="margin: 50px">
        Basic
    </div>

    <div tooltip={{ placement: 'up', text: "This tooltip is displayed on top, unless you scroll..." }} style="margin: 50px">
        Displayed on top!
    </div>

    <div tooltip={{ placement: 'up', title: 'Hello', text: "It seems that you're really interested in tooltips." }} style="margin: 50px">
        Title
    </div>

    <TextField
            value-bind="$page.text" required visited placeholder="Validation" style="margin: 50px"
            tooltip="Tooltips are commonly used to show validation errors on form elements."
        />

    <TextField
        value-bind="$page.text" required visited placeholder="More Validation" style="margin: 50px"
        errorTooltip={{placement: 'up', alwaysVisible: true, title: "Validation Error"}}
    />

    <div style="padding: 10px" tooltip={{ mouseTrap: true, items: <cx><Md>
        Tooltips can contain any content. For example, we can add [a link to the overlays page](~/widgets/overlays) or **make some text bold** because
        we're using markdown here. Any other component can be used here too, however, tooltips work best with text and images.

        Please note that tooltip elements are appended to the `body` element, hence only the global style rules apply.

        In order to support a link click inside a tooltip, the tooltip needs to trap the click event so it doesn't disappear.

        </Md></cx> }}>
        Rich content
    </div>

    <div style="margin: 50px" tooltip={{ mouseTrap: true, items: <cx>
            <Grid columns={[
            { field: 'fullName', header: 'Name', sortable: true },
            { field: 'phone', header: 'Phone' }
            ]} records-bind="$page.records"/>
        </cx>}}>
        Component inside
    </div>

    <div tooltip={{ alwaysVisible: { bind: '$page.showTooltip'}, placement: 'down', text: "Tooltips can be set to be always visible." }} style="margin: 50px">
        <Checkbox value-bind="$page.showTooltip">Always visible</Checkbox>
    </div>

    <div tooltip={{ visible: { bind: '$page.tooltipVisible'}, alwaysVisible: { bind: '$page.tooltipVisible'}, placement: 'down', text: "This tooltip is visible only while the checkbox is checked." }} style="margin: 50px">
        <Checkbox value-bind="$page.tooltipVisible">Controlled visibility</Checkbox>
    </div>
    <div tooltip={{text: "I'm right behind you.", trackMouse: true, offset: 20}}>
            Mouse tracking
    </div>
</div>

Copied!Cx Fiddle

Configuration

Property	Description	Type
closeOnEscape	Set to `true` to make the window automatically close if the Esc key is pressed on the keyboard. Default value is `false`.	boolean
mouseTrap	Tooltips are hidden as soon as the mouse leaves the related widget. Set this to `true` to keep the tooltip while the mouse is inside the tooltip itself.	string
offset	Distance in pixels from related elements. Default is `8`.	number
placement	Placement strategy. Defaults to `right up down left`. `top` and `bottom` values are also valid and behave the same as `up` and `down`.	string
text	Text to be displayed inside the tooltip.	string
title	Text to be displayed in the header.	string
touchBehavior	This property controls how tooltips behave on touch events. Default value is `toggle` which means that the tooltip is shown on first tap and closed on the second tap. Use `ignore` to skip showing tooltips on touch events.	string
trackMouse	Set to `true` to make the tooltip follow the mouse movement.	string
alwaysVisible	Set to `true` to make the tooltip always visible. This is useful e.g. in product tours, when instructions need to be shown, even if the mouse pointer is not around.	boolean
autoFocus	Set to `true` to automatically focus the dropdown when it's shown.	boolean
autoFocusFirstChild	Set to `true` to automatically find and focus the first chinld in the dropdown when it's shown.	boolean
baseClass	Base CSS class to be applied to the field. Defaults to `tooltip`.	string
centerX	Set to `true` to initially place the overlay in the center of the page horizontally.	boolean
centerY	Set to `true` to initially place the overlay in the center of the page vertically.	boolean
class className	Additional CSS classes to be applied to the element. If an object is provided, all keys with a "truthy" value will be added to the CSS class list.	string/object
closeOnScrollDistance	The dropdown will be automatically closed if the page is scrolled a certain distance. Default value is `50`.	number
containerStyle	Style to be applied to the overlay's container element.	string
destroyDelay	Number of milliseconds to wait, before removing the element from the DOM. Used in combination with the `animate` property.	number
dismissOnFocusOut	Set to `true` to dismiss the overlay when it loses focus.	boolean
dismissOnPopState	Set to `true` to dismiss the window if the user presses the back button in the browser.	boolean
focusable	Set to true to make the top level overlay element focusable.	boolean
globalMouseTracking	Set to `true` to rely on browser's window `mousemove` event for getting mouse coordinates instead of using the element that tooltip is attached to.	string
items children	List of child elements.	array
layout	Define an inner layout.	string/object
matchMaxWidth	Constrains the component's width to the maximum width of its parent, maintaining a responsive design within limits.	boolean
matchWidth	Ensures the component matches the width of its parent container, creating a cohesive layout.	boolean
mod	Appearance modifier. For example, `mod="big"` will add the CSS class `.cxm-big` to the block element.	string/array
onMove	A callback function which fires while the overlay is being moved around.	function
onResize	A callback function which fires while the overlay is being resized.	function
placementOrder	Defines available placement options. The dropdown will be pick the placement to maximize content visibility. Supported options are `top`, `right`, `down` and `left` and corner values `up-left`, `up-right`, `down-left`, `down-right`, `right-down`, `right-up`, `left-up`, `left-down`. Default value is `"up down right left"`.	string
plainText	Set to `true` to avoid converting inner strings to templates. Default is `false`.	boolean
preserveWhitespace ws	Keep whitespace in text based children. Default is `false`. See also `trimWhitespace`.	boolean
putInto contentFor	Used with outer layouts. Specifies the name of the content placeholder which should render the widget.	string
resizeWidth	resizeWidth	number
style	Style object applied to the wrapper div. Used for setting the dimensions of the element.	string/object
trimWhitespace	Remove all whitespace in text based children. Default is `true`. See also `preserveWhitespace`.	boolean
vdomKey	Key that will be used as the key when rendering the React component.	string
visible if	Visibility of the widget. Defaults to `true`.	boolean
zIndex	zIndex	number

Documentation

Tooltips