Tooltip

<caos-tooltip>

a short label shown on hover or focus

May be placed on a record page, an app’s home page, a page inside an app, a step of a guided flow, the utility bar and a seam in the workspace frame.

Inputs

Name	Attribute	Description	Type	Default	Required
text	text, markup only	The tip. A short phrase describing the thing it wraps. It is ignored when something is slotted into the tip slot, so the two never fight over the bubble.	text	none declared	Optional
placement	placement, markup only	Which side of the trigger the bubble prefers: top, bottom, left or right. Where that side has no room and the opposite side does, it opens there instead, and it slides along the side it opens on so the whole bubble stays on screen.	text — one of top, bottom, left, right	top	Optional

Events

This piece raises no events.

Slots

Name	What goes in it
the default slot	The trigger — the thing being described. It is wrapped in a focusable span, so it is reachable by keyboard even when what it holds is plain text.
tip	Richer tip content than a line of text, for the cases the text attribute cannot carry. Never an action.

Styling hooks

Design token	What it controls
--caos-color-surface	The fill of the bubble.
--caos-color-border	The edge of the bubble.
--caos-color-text	The tip text.
--caos-shadow-float	The one elevation reserved for pieces that float.
--caos-radius-sm	The corner radius of the bubble, and of the focus ring on the trigger.
--caos-focus-ring	The ring drawn on the trigger when it is reached by keyboard.
--caos-space-2	The vertical padding inside the bubble.
--caos-space-3	The horizontal padding inside the bubble.
--caos-font	The typeface the tip is set in.

Methods

Nothing else drives this piece by calling it.

Readable state

Nothing on this piece can be read back.

Styling parts

Part	Which piece of it	When it is there
::part(trigger)	the thing being described, which the tip hangs off	Always
::part(tip)	the tip itself	Always

When to use it

A short description of one control, wanted only by somebody who is already looking at it. If the words matter enough that everybody should read them, they should not be hidden behind a hover.

What to use instead

• InlineHint — The explanation is worth permanent screen space — it says what a field drives, and everybody needs it.
• OverflowMenu — What opens carries actions. A tooltip never does: it is not reachable by pointer and holds nothing to press.
• Toast — The message is about something that just happened rather than about the control under the pointer.

Accessibility

The trigger wrapper is focusable and points aria-describedby at the bubble, which carries role=“tooltip”, so the tip is announced as a description of the thing it wraps. It reveals on focus as well as on hover, so it is reachable without a pointer, and Escape blurs the trigger to dismiss it. Hidden, it is out of the accessibility tree entirely rather than merely invisible. What is left to the author: this is a DESCRIPTION, not a name — an icon-only button still needs its own accessible label, and a tooltip is not a substitute for one.

Examples

On a control

The ordinary case: a control wrapped in the tip that describes it, opening above at the default placement.

{
  "id": "example",
  "section": "On a control",
  "columns": 1,
  "items": [
    {
      "id": "tooltip_1",
      "type": "component",
      "key": "tooltip",
      "inputs": {
        "text": "Adds an empty row to the table below.",
        "placement": "top"
      },
      "children": [
        {
          "id": "button_2",
          "type": "component",
          "key": "button",
          "inputs": {
            "variant": "secondary"
          },
          "children": [
            "Add line"
          ]
        }
      ]
    }
  ]
}

<caos-tooltip text="Adds an empty row to the table below." placement="top">
  <caos-button variant="secondary">Add line</caos-button>
</caos-tooltip>

Opening downward

The same tooltip with placement set to bottom — the side the author prefers, and the room the surrounding page has to leave clear moves with it.

{
  "id": "example",
  "section": "Opening downward",
  "columns": 1,
  "items": [
    {
      "id": "tooltip_1",
      "type": "component",
      "key": "tooltip",
      "inputs": {
        "text": "Adds an empty row to the table below.",
        "placement": "bottom"
      },
      "children": [
        {
          "id": "button_2",
          "type": "component",
          "key": "button",
          "inputs": {
            "variant": "secondary"
          },
          "children": [
            "Add line"
          ]
        }
      ]
    }
  ]
}

<caos-tooltip text="Adds an empty row to the table below." placement="bottom">
  <caos-button variant="secondary">Add line</caos-button>
</caos-tooltip>