# Tooltip

Tooltips sind kurze Hilfselemente, die beim Hovern über ein Element zusätzliche Informationen anzeigen.

## Overview

# Playground

Verwende `<TooltipTrigger />` und `<Tooltip />` in Kombination mit der gewünschten Component, um beim Hovern der Component einen Tooltip anzuzeigen.

```tsx
import {
  Button,
  IconEdit,
  Tooltip,
  TooltipTrigger,
} from "@mittwald/flow-react-components";

<TooltipTrigger>
  <Button aria-label="Bearbeiten" variant="plain">
    <IconEdit />
  </Button>
  <Tooltip>Bearbeiten</Tooltip>
</TooltipTrigger>
```


## Develop

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `offset` | `number` | `0` | The additional offset applied along the main axis between the element and its anchor element. |
| `translate` | `"yes" \| "no"` | - | - |
| `arrowBoundaryOffset` | `number` | `0` | The minimum distance the arrow's edge should be from the edge of the overlay element. |
| `className` | `ClassNameOrFunction<TooltipRenderProps>` | `'react-aria-Tooltip'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `triggerRef` | `RefObject<Element>` | - | The ref for the element which the tooltip positions itself with respect to. When used within a TooltipTrigger this is set automatically. It is only required when used standalone. |
| `isEntering` | `boolean` | - | Whether the tooltip is currently performing an entry animation. |
| `isExiting` | `boolean` | - | Whether the tooltip is currently performing an exit animation. |
| `UNSTABLE_portalContainer` _(deprecated)_ | `Element` | `document.body` | The container element in which the overlay portal will be placed. This may have unknown behavior depending on where it is portalled to. @deprecated - Use a parent UNSAFE_PortalProvider to set your portal container instead. |
| `placement` | `Placement` | `'top'` | The placement of the tooltip with respect to the trigger. |
| `containerPadding` | `number` | `12` | The placement padding that should be applied between the element and its surrounding container. |
| `crossOffset` | `number` | `0` | The additional offset applied along the cross axis between the element and its anchor element. |
| `shouldFlip` | `boolean` | `true` | Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely. |
| `isOpen` | `boolean` | - | Whether the element is rendered. |
| `defaultOpen` | `boolean` | - | Whether the overlay is open by default (uncontrolled). |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `dir` | `string` | - | - |
| `lang` | `string` | - | - |
| `hidden` | `boolean` | - | - |
| `inert` | `boolean` | - | - |
| `children` | `ReactNode` | - | - |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onOpenChange` | `((isOpen: boolean) => void)` | - | Handler that is called when the overlay's open state changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onClickCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onAuxClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onAuxClickCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onContextMenu` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onContextMenuCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onDoubleClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onDoubleClickCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseDown` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseDownCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseEnter` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseLeave` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseMove` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseMoveCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOut` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOutCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOver` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOverCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseUp` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseUpCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onTouchCancel` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchCancelCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchEnd` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchEndCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchMove` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchMoveCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchStart` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchStartCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onPointerDown` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerDownCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerMove` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerMoveCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerUp` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerUpCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerCancel` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerCancelCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerEnter` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerLeave` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOver` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOverCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOut` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOutCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onGotPointerCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onGotPointerCaptureCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onLostPointerCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onLostPointerCaptureCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onScroll` | `UIEventHandler<HTMLDivElement>` | - | - |
| `onScrollCapture` | `UIEventHandler<HTMLDivElement>` | - | - |
| `onWheel` | `WheelEventHandler<HTMLDivElement>` | - | - |
| `onWheelCapture` | `WheelEventHandler<HTMLDivElement>` | - | - |
| `onAnimationStart` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationStartCapture` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationEnd` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationEndCapture` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationIteration` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationIterationCapture` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onTransitionCancel` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionCancelCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionEnd` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionEndCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionRun` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionRunCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionStart` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionStartCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |


## Guidelines

# Grundlagen

## Best practices

Achte bei der Verwendung eines Tooltips darauf, dass ...

- diese verwendet werden, um knappe Informationen mit niedriger Priorität
  bereitzustellen – z. B. eine kurze Beschreibung eines
  [Icons](/04-components/content/icon/overview).
- der Tooltip nur ergänzende Informationen enthält und keine wichtige
  Information (z. B. Error-Meldung oder Feedback) der Benutzeroberfläche
  ersetzt. Es muss immer bedacht werden, dass beispielsweise auf dem Smartphone
  Tooltips vom User nicht wahrgenommen werden.
- der Inhalt kurz, verständlich und präzise formuliert ist. Tooltips bestehen
  meist nur aus 1-3 Wörtern.
- er erst beim Hovern oder Fokussieren erscheint.
- innerhalb nur Text verwendet wird. In einem Tooltip sollten keine
  [Buttons](/04-components/actions/button/overview),
  [Links](/04-components/navigation/link/overview) oder interaktiven Inhalte
  enthalten sein.
- sie nicht für Elemente mit vorhandener sichtbarer Beschriftung eingesetzt
  werden.

## Verwendung

Verwende einen Tooltip, um ...

- zusätzliche kurze Hinweise oder Kontext zu einem Element der
  Benutzeroberfläche bereitzustellen, ohne die Benutzeroberfläche zu überladen.
  Für umfangreichere Informationen – die über den direkten Kontext des Elements
  hinausgehen – eignet sich z. B. ein
  [ContextualHelp](/04-components/overlays/contextual-help/overview).
- Symbole, Icons oder verkürzte Bezeichnungen zu erklären. Ein Tooltip kann
  Usern beispielsweise helfen,
  [das Icon eines Buttons](/04-components/actions/button/overview) korrekt zu
  interpretieren.

