# Help Tooltip

An info icon that explains a title, a figure or a field on hover and keyboard focus.

```tsx
import { HelpTooltip } from "@zenoxai/ui/patterns/help-tooltip"

function HelpTooltipDemo() {
  return (
    <div className="flex items-center gap-1.5 text-sm text-text-secondary">
      Risk score
      <HelpTooltip content="Combines severity, asset exposure and known exploits. Recalculated every hour." />
    </div>
  )
}
```

## Usage

```tsx
import { HelpTooltip } from "@zenoxai/ui/patterns/help-tooltip"

export function RiskScoreLabel() {
  return (
    <span className="gap-1.5 flex items-center">
      Risk score
      <HelpTooltip content="Combines severity, asset exposure and known exploits." />
    </span>
  )
}
```

Place it right after the text it explains: a page title, a KPI label, a column header, a field
label. [Page Header](/patterns/page-header) and [Stat Tile](/patterns/stat-tile) render one for
you through their `hint` prop.

Use it for supporting information only: how a figure is computed, where data comes from, what
a term means. Anything the user must read to complete the task, such as a format, a limit or a
consequence, belongs in visible text. A user who never hovers the icon must still be able to
finish.

Keep the content to a sentence or two of plain text. For longer explanations, link to a page.
For a label on any other control, use [Tooltip](/components/tooltip).

## Examples

### Next to a field

The tooltip explains why the setting exists. The allowed range is required to fill the field
correctly, so it stays visible in the field description.

```tsx
import { Field, FieldDescription, FieldLabel } from "@zenoxai/ui/components/field"
import { Input } from "@zenoxai/ui/components/input"
import { HelpTooltip } from "@zenoxai/ui/patterns/help-tooltip"

function HelpTooltipWithField() {
  return (
    <Field className="max-w-xs">
      <div className="flex items-center gap-1.5">
        <FieldLabel htmlFor="retention">Retention period (days)</FieldLabel>
        <HelpTooltip content="Events older than this are deleted from search. Reports keep their own copy." />
      </div>
      <Input id="retention" type="number" defaultValue={90} />
      <FieldDescription>Between 30 and 365 days.</FieldDescription>
    </Field>
  )
}
```

### Sizes

`sm` (the default, 14px) sits beside body text, labels and column headers. `md` (16px) sits
beside a page or section title. Either way the pointer target extends 6px around the icon (26
or 28px), above the 24px that WCAG 2.5.8 asks for, without changing the layout.

```tsx
import { HelpTooltip } from "@zenoxai/ui/patterns/help-tooltip"

function HelpTooltipSizes() {
  return (
    <div className="flex flex-col items-start gap-4">
      <div className="flex items-center gap-1.5 text-xl font-semibold">
        Threat intelligence
        <HelpTooltip
          size="md"
          content="Indicators collected from your feeds and from Zenox research."
        />
      </div>
      <div className="flex items-center gap-1.5 text-sm text-text-secondary">
        Mean time to resolve
        <HelpTooltip content="Median time from alert creation to resolution, last 30 days." />
      </div>
    </div>
  )
}
```

### With rich content

When `content` is not a string, pass `label`. Without it the icon is announced as "More
information", which says nothing about the subject.

```tsx
import { HelpTooltip } from "@zenoxai/ui/patterns/help-tooltip"

function HelpTooltipWithLabel() {
  return (
    <div className="flex items-center gap-1.5 text-sm text-text-secondary">
      Source filter
      <HelpTooltip
        label="About the source filter"
        content={
          <>
            Matches the <code className="font-mono">source.ip</code> field of
            each event, including private ranges.
          </>
        }
      />
    </div>
  )
}
```

## Accessibility

- The icon is a real `<button>`, reachable with Tab. The tooltip opens on hover and on keyboard
  focus, and Escape closes it.
- When `content` is a string it doubles as the button's accessible name, so screen readers read
  the explanation itself. Pass `label` for anything else.
- Touch screens have no hover, so do not count on the tooltip being seen there. It is one more
  reason to keep required information visible.
- Do not put links or buttons in `content`: the tooltip closes as soon as the pointer or focus
  leaves the icon. Use a [Popover](/components/popover) for interactive content.

## API reference

`import { ... } from "@zenoxai/ui/patterns/help-tooltip"`

### HelpTooltip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| content (required) | `ReactNode` |  | The explanation shown on hover and focus. Keep it to a sentence or two. |
| label | `string` |  | Accessible name of the trigger. Defaults to the content when it is a string, so a screen reader hears the explanation itself. |
| size | `"sm" \| "md"` | `sm` | Icon size step. `sm` sits beside body text, `md` beside a page title. |