Tooltip - CxJS Documentation

import { enableTooltips } from 'cx/widgets';

Tooltips provide additional information about an element when the user hovers over it. In CxJS, tooltips are also used to display validation errors on form fields.

To enable tooltips, call enableTooltips() at application startup. Tooltips are not automatically enabled to keep bundle sizes small for applications that don’t need them.

Basic Usage

The tooltip prop accepts either a string or a configuration object with properties like text, title, and placement.

 <div className="flex flex-col items-start gap-4">
  <div tooltip="This is a basic tooltip." className="cursor-help">
    Basic tooltip
  </div>

  <div
    tooltip={{ placement: "up", text: "This tooltip is displayed on top." }}
    className="cursor-help"
  >
    Placement: up
  </div>

  <div
    tooltip={{ placement: "right", text: "Tooltip on the right side!" }}
    className="cursor-help"
  >
    Placement: right
  </div>

  <div
    tooltip={{
      placement: "up",
      title: "Tooltip Title",
      text: "This tooltip has a title.",
    }}
    className="cursor-help"
  >
    With title
  </div>
</div> 

Basic tooltip

Placement: up

Placement: right

With title

Form Validation

Tooltips are commonly used to display validation errors. Use the errorTooltip prop to customize how validation errors are displayed.

 <div className="flex flex-col items-start gap-4">
  <TextField
    value={m.text}
    required
    visited
    placeholder="Required field"
    tooltip="Validation errors are shown in tooltips"
  />

  <TextField
    value={m.text}
    required
    visited
    placeholder="Error tooltip always visible"
    errorTooltip={{
      placement: "right",
      alwaysVisible: true,
      title: "Validation Error",
      mod: "error",
    }}
  />
</div> 
 interface PageModel {
  text: string;
}

const m = createModel<PageModel>(); 
 import { createModel } from "cx/data";
import { enableTooltips, TextField } from "cx/widgets";
enableTooltips(); 

Interactive Features

Tooltips support advanced features like controlled visibility, mouse tracking, and rich content.

 <div className="flex flex-col items-start gap-4">
  <div
    tooltip={{
      alwaysVisible: m.showTooltip,
      placement: "right",
      text: "Tooltips can be set to always visible.",
    }}
  >
    <Checkbox value={m.showTooltip}>Always visible</Checkbox>
  </div>

  <div
    tooltip={{
      visible: m.tooltipVisible,
      alwaysVisible: m.tooltipVisible,
      placement: "right",
      text: "This tooltip is visible only while the checkbox is checked.",
    }}
  >
    <Checkbox value={m.tooltipVisible}>Controlled visibility</Checkbox>
  </div>

  <div
    tooltip={{ text: "I follow your mouse!", trackMouse: true, offset: 20 }}
    className="cursor-help"
  >
    Mouse tracking
  </div>
</div> 
 interface PageModel {
  showTooltip: boolean;
  tooltipVisible: boolean;
}

const m = createModel<PageModel>(); 
 import { createModel } from "cx/data";
import { enableTooltips, Checkbox } from "cx/widgets";
enableTooltips(); 

Always visible

Controlled visibility

Mouse tracking

Rich Content

Tooltips can contain rich content including formatted text, links, and even complex components. Use mouseTrap: true to keep the tooltip open while the mouse is inside it, allowing users to interact with the content.

 <div controller={PageController} className="flex flex-col items-start gap-4">
  <div
    className="cursor-help"
    tooltip={{
      mouseTrap: true,
      children: (
        <div className="max-w-sm">
          <p>
            Tooltips can contain any content. For example, we can add{" "}
            <Link href="https://cxjs.io" target="_blank">
              a link to the CxJS website
            </Link>{" "}
            or <strong>make some text bold</strong>.
          </p>
          <p className="mt-2">
            Any component can be used here too, however, tooltips work best with
            text and images.
          </p>
          <p className="mt-2">
            Note that tooltip elements are appended to the <code>body</code>{" "}
            element, hence only global style rules apply.
          </p>
          <p className="mt-2">
            To support link clicks inside a tooltip, set{" "}
            <code>mouseTrap: true</code> so it doesn't disappear.
          </p>
        </div>
      ),
    }}
  >
    Rich content
  </div>

  <div
    className="cursor-help"
    tooltip={{
      mouseTrap: true,
      children: (
        <Grid
          records={m.records}
          columns={[
            { field: "name", header: "Name", sortable: true },
            { field: "phone", header: "Phone", sortable: true },
          ]}
        />
      ),
    }}
  >
    Component inside (Grid)
  </div>
</div> 
 class PageController extends Controller<PageModel> {
  onInit() {
    this.store.set(m.records, [
      { id: 1, name: "John Doe", phone: "555-1234" },
      { id: 2, name: "Jane Smith", phone: "555-5678" },
      { id: 3, name: "Bob Wilson", phone: "555-9012" },
    ]);
  }
} 
 interface PageModel {
  records: Array<{ id: number; name: string; phone: string }>;
}

const m = createModel<PageModel>(); 
 import { createModel } from "cx/data";
import { Controller } from "cx/ui";
import { enableTooltips, Link, Grid } from "cx/widgets";
enableTooltips(); 

Rich content

Component inside (Grid)

Touch Devices

Touch devices don’t have precise mouse pointer location, so tooltips are shown/hidden when the user taps the element. To make tooltips ignore touch events, set touchBehavior to "ignore".

To make all tooltips ignore touch events by default:

Tooltip.prototype.touchBehavior = "ignore";

Configuration

Property	Type	Description
`text`	`string`	Text displayed inside the tooltip.
`title`	`string`	Text displayed in the tooltip header.
`children` / `items`	`any`	Rich content to display inside the tooltip.
`placement`	`string`	Placement strategy. Defaults to `"right up down left"`. Also accepts `"top"` and `"bottom"`.
`offset`	`number`	Distance in pixels from the related element. Default is `8`.
`visible`	`boolean`	Controls tooltip visibility.
`alwaysVisible`	`boolean`	Makes the tooltip always visible (useful for product tours).
`mouseTrap`	`boolean`	Keeps the tooltip visible while the mouse is inside it.
`trackMouse`	`boolean`	Makes the tooltip follow mouse movement.
`touchBehavior`	`string`	Controls touch event behavior: `"toggle"` (default) or `"ignore"`.
`globalMouseTracking`	`boolean`	Uses window `mousemove` event instead of element events for coordinates.