# Tooltip

A small popup that displays helpful information through an attachment on a target element.

## Usage

Apply via the `tooltip` attachment; the renderer auto-mounts (never place manually).
```svelte
<button {@attach tooltip({ text: "Hint" })}>Hover</button>
```

## Anatomy

The internal renderer auto-mounts to `document.body` on first hover or touch long-press; do not place it manually. Pointer devices show on hover, while touch devices show after holding for `delay` ms and hide on release or scroll.

```svelte
<div class="whole" role="tooltip">
  {#if content}
    {content(text, variant, flipped)}
  {:else}
    {text}
  {/if}
</div>
```

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `text` | `string` | - | Tooltip text and accessible description for the target element |
| `content` | `Snippet` | - | Custom tooltip snippet receiving text, variant, and flipped state; replaces the default text renderer |
| `position` | `Position` | `"top"` | Display position relative to the target element |
| `align` | `Align` | `"center"` | Tooltip alignment relative to the target element |
| `offset` | `Vector` | `{ x: 0, y: 0 }` | Offset from the default position |
| `delay` | `number` | `1000` | Time in milliseconds before the tooltip appears; `0` is immediate and a negative value falls back to `1000` |
| `cursor` | `boolean` | `false` | Whether the tooltip follows cursor movement on pointer devices |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Tooltip variant |
## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

No automatic switching.

### Default Class Name

`svs-tooltip`

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Trigger element: `aria-description` set to the tooltip text when `text` is a non-empty string.
- Tooltip (`whole` `<div>`): `role="tooltip"`.

## Exports

### Types

```ts
type Vector = { x: number; y: number };
type Position = "top" | "right" | "bottom" | "left";
type Align = "start" | "center" | "end";
interface TooltipParams {
  text?: string;
  content?: Snippet<[string, SVSVariant, boolean]>; // Snippet<[text, variant, flipped]>
  position?: Position; // ("top")
  align?: Align; // ("center")
  offset?: Vector; // ({ x: 0, y: 0 })
  delay?: number; // (1000; 0 = immediate, negative = 1000)
  cursor?: boolean; // (false)
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
}
type TooltipDefaults = Omit<TooltipParams, "text" | "content">;
```

### Others

```ts
// Attachment factory for standard HTML elements (`{@attach tooltip(params)}`)
// and SvSeeds components (`attach={tooltip(params)}`).
function tooltip(params: TooltipParams): Attachment<HTMLElement>;

// Sets library-wide defaults. Callable repeatedly; last call wins per key.
function initTooltip(defaults: Partial<TooltipDefaults>): void;
```

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=TooltipBasic.svelte
<script lang="ts">
  import { tooltip } from "svseeds";

  const styling = {
    whole: "p-1 flex justify-center items-center bg-teal-500 select-none",
  };
  const myProps = {
    text: "Hello!!",
    offset: { x: 0, y: -10 },
    styling,
  };
</script>

<div class="p-2 rounded-md border select-none" {@attach tooltip(myProps)}>Hover HERE</div>
```
### With Interactive Variant

**Code**

```svelte src=TooltipPract.svelte
<script lang="ts">
  import { Button, tooltip } from "svseeds";
  import Heart from "@lucide/svelte/icons/heart";

  let { variant = $bindable() } = $props();
  const variantStyle = {
    neutral: "[--color-bg:oklch(55.2%_0.016_285.938)]",
    active: "[--color-bg:oklch(60%_0.118_184.704)]",
    inactive: "[--color-bg:oklch(57.7%_0.245_27.325)]",
    blue: "[--color-bg:oklch(54.6%_0.245_262.881)]",
    yellow: "[--color-bg:oklch(68.1%_0.162_75.834)]",
    sky: "[--color-bg:oklch(58.8%_0.158_241.966)]",
  };
  const styling = {
    whole: {
      base: "relative py-1 px-2 flex justify-center items-center bg-(--color-bg) rounded-sm select-none",
      ...variantStyle,
    },
  };
  const myProps = {
    text: "LIKE",
    content: children,
    position: "bottom" as const,
    offset: { x: 0, y: 15 },
    styling,
  };
</script>

<Button attach={tooltip({ ...myProps, variant })}>
  <Heart class="size-5" />
</Button>

{#snippet children(text: string, _variant: string, isFlipped: boolean)}
  {@const cls = [
    "absolute left-1/2 -translate-x-1/2 size-3 bg-(--color-bg)",
    { "-top-[11px]": !isFlipped, "-bottom-3": isFlipped },
    { "[clip-path:polygon(0_100%,100%_100%,50%_0)]": !isFlipped, "[clip-path:polygon(0_0,100%_0,50%_100%)]": isFlipped },
  ]}
  <div class={cls}></div>
  {text}
{/snippet}
```