# Tooltip

```ts
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`.

```tsx
import { enableTooltips } from "cx/widgets";

enableTooltips();

export default (
  <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>
);

```

## Form Validation

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

```tsx
import { createModel } from "cx/data";
import { enableTooltips, TextField } from "cx/widgets";

enableTooltips();

interface PageModel {
  text: string;
}

const m = createModel<PageModel>();

export default (
  <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>
);

```

## Interactive Features

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

```tsx
import { createModel } from "cx/data";
import { enableTooltips, Checkbox } from "cx/widgets";

enableTooltips();

interface PageModel {
  showTooltip: boolean;
  tooltipVisible: boolean;
}

const m = createModel<PageModel>();

export default (
  <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>
);
```

## 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.

```tsx
import { createModel } from "cx/data";
import { Controller } from "cx/ui";
import { enableTooltips, Link, Grid } from "cx/widgets";

enableTooltips();

interface PageModel {
  records: Array<{ id: number; name: string; phone: string }>;
}

const m = createModel<PageModel>();

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" },
    ]);
  }
}

export default (
  <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>
);

```

## 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:

```tsx
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. |