Skip to main content

Tooltip

The Tooltip component is a wrapper that displays a tooltip when the user hovers over elements inside it. Tooltips can show plain text via data-tooltip-text attributes on child elements, or rich custom content via a resolver function and a dedicated content component.

Initialization​

To add a Tooltip to a page, import it and wrap the target elements:

App.svelte
<script>
  import { Tooltip } from "@svar-ui/svelte-core";
</script>

<Tooltip>
  <div data-tooltip-text="Hello">Hover me</div>
</Tooltip>

A tooltip appears when the user hovers over a child element that has a data-tooltip-text attribute (or when the custom resolver returns a value for it).

Showing plain text tooltips​

The simplest way to attach a tooltip to a child element is the data-tooltip-text attribute. When no custom content or resolver is provided, the default resolver reads this attribute automatically:

<Tooltip at="bottom-center" arrow>
  <div data-tooltip-text="Saved successfully">Save</div>
</Tooltip>

Using the tooltip prop on built-in controls​

The following controls accept a tooltip?: string prop that sets data-tooltip-text on the control's root element, so the tooltip activates automatically when the control is wrapped in <Tooltip>:

Button, Counter, Icon, Combo, MultiCombo, Select, RichSelect, ColorPicker, ColorSelect, DatePicker, DateRangePicker, TimePicker, Slider, Text, TextArea, TwoState.

Without <Tooltip> wrapper, this prop has no visible effect.

<script>
  import { Tooltip, Button } from "@svar-ui/svelte-core";
</script>

<Tooltip at="bottom" arrow>
  <Button tooltip="Save the document" icon="wxi-save" />
</Tooltip>
note

Tooltip does not interact with the HTML title attribute. Setting tooltip on a control does not affect its title prop and vice versa. Both can be set simultaneously when each displays its own tooltip (the browser's native one and the SVAR one) but make sure it's not redundant in your case.

Segmented and Tabs: per-option tooltip​

For Segmented and Tabs, tooltip text is set per option via the tooltip field of each option object rather than on the component itself. It sets data-tooltip-text on the option's <button> element:

<script>
  const options = [
    { id: 1, icon: "wxi-view-sequential", label: "List", tooltip: "List view" },
    { id: 2, icon: "wxi-view-grid", label: "Grid", tooltip: "Grid view" },
  ];
</script>

<Tooltip at="bottom" arrow>
  <Segmented {options} />
</Tooltip>

Render custom content in a tooltip​

To show rich content in a tooltip, provide a Svelte component via content and a resolver function that reads data from the hovered element.

App.svelte
<script>
  import { Tooltip } from "@svar-ui/svelte-core";
  import MyTooltipContent from "./MyTooltipContent.svelte";
</script>

<Tooltip
  content={MyTooltipContent}
  resolver={el =>
    el.matches(".grid > div")
      ? { x: +el.dataset.x, y: +el.dataset.y, value: +el.textContent }
      : null}
>
  <div class="grid">
    <div data-x="0" data-y="0">10</div>
    <div data-x="1" data-y="0">20</div>
  </div>
</Tooltip>

The resolver is called on event.target and its ancestors one by one until it returns a non-null value. Here it uses el.matches() to target grid cells, reads coordinates from data-x / data-y attributes and the cell value from textContent, and returns { x, y, value }, which the Tooltip spreads as props into MyTooltipContent.

MyTooltipContent.svelte receives the keys as props and visualizes them:

MyTooltipContent.svelte
<script>
  const { x, y, value } = $props();
</script>
<div>Value {value} at ({x}, {y})</div>

Resolver returns:

  • string — displayed as plain text when no content component is set; passed as <Content data={string} /> when content is set
  • object — spread as props into content (<Content {...result} />); when no content is set, result.data is rendered as text
  • null — no tooltip is shown for this element

Following the cursor​

Set at to "point" to make the tooltip track the mouse cursor instead of anchoring to the hovered element:

<Tooltip at="point">
  <div class="chart" data-tooltip-text="Click to drill down" />
</Tooltip>
note

The arrow prop is ignored when at is "point".

Configuring tooltip position​

Use the at property to control where the tooltip appears relative to the hovered element. The default placement is "top-center":

<Tooltip at="bottom-end" arrow>
  <button data-tooltip-text="Delete item">Delete</button>
</Tooltip>

The directional arrow is hidden by default. Set arrow to true to show it.

Configuring tooltip behavior​

Use delay to set how long (in milliseconds) the user must hover before the tooltip appears. The default is 300:

<Tooltip delay={500}>
  <div data-tooltip-text="Takes a moment to show">Hover</div>
</Tooltip>

Tooltips are disabled on touch devices by default. Set touch to true to enable them:

<Tooltip touch={true}>
  <div data-tooltip-text="Touch tooltip">Tap me</div>
</Tooltip>

Showing tooltips on overflowing text​

Set overflow to true to show the tooltip only when the anchor element's text is not fully visible. This is useful in tables or lists where cells have a fixed width. The tooltip appears only when the text does not fit, and stays hidden when it does.

<Tooltip overflow>
  <div class="cell" data-tooltip-text="Very long text that may overflow">
    Very long text that may overflow
  </div>
</Tooltip>

<style>
  .cell {
    width: 120px;
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
  }
</style>
note

The overflow check applies only to the default resolver. It has no effect when a custom resolver is provided.

Nesting tooltips​

You can nest <Tooltip> components. The innermost tooltip takes precedence over the outer one when the user hovers over overlapping elements:

<Tooltip at="top-center" arrow>
  <div data-tooltip-text="Outer tooltip">
    Outer
    <Tooltip at="right-center" arrow>
      <div data-tooltip-text="Inner tooltip">Inner</div>
    </Tooltip>
  </div>
</Tooltip>

Styling a tooltip​

You can add a custom CSS class to the tooltip popup via the css property. Use it to override CSS variables and customize the tooltip appearance:

<Tooltip css="my-tooltip">
  <div data-tooltip-text="Styled tooltip">Hover</div>
</Tooltip>

<style>
  :global(.my-tooltip) {
    --wx-tooltip-background: white;
    --wx-tooltip-font-color: black;
    --wx-tooltip-padding: 8px 12px;
    --wx-border-radius: 8px;
  }
</style>

See the full list of available CSS variables in the css property reference.