Anatomy
Note: Image is not to scale
- Content Container
- Arrow
Options
Positioning
The tooltip can be positioned top, left, right, and bottom with each having ability to position at the start, or end of the content container.
Note: This option sets the preferred position of the tooltip to render against when open. Will be reveresed when collisions occur with other elements.
Density
There are two options for the property density: compact and default.
Offset
The option offset can use any spacing token to offset its position from the origin point of the tooltip. The default offset is the spacing token 025.
Behavior
Avoids collisions
When appropriate, helper text should be placed closest to the Legend.
Guidance
Do not hide content
A tooltip is not meant to hide necessary contextual information. It should only be used as a supplementary element. The nautre of a tooltip is non-persistent and should not require users to discover content within a tooltip.
Avoid nesting actionable elements
The nautre of the tooltip is non-persistent. When the user is required to take an action on an element nested inside the tooltip it makes the action less accessible for those with limited mobility.
Do not nest Popovers or Tooltips
Tooltips should not have additional tooltips or popover within the same container.
Accessibility
Design considerations
While tooltips are a convenient way of revealing content, please keep in mind the nautre of a tooltip and how it shows/hides on hover. consider alternatives like a more persistent element like a popover.
Keyboard controls
Tooltips will show/hide without delay when the trigger is in focus and tab is selected on the keyboard. If the tooltip is open and either escape, space, or enter is selected on the keyboard, it will close the tooltip.
API Reference
TooltipRoot
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| open | boolean | ---- | False | |
| defaultOpen | boolean | ---- | False | |
| onOpenChange | (open: boolean) => void | ---- | False | |
| delayDuration | The duration from when the pointer enters the trigger until the tooltip gets opened. This will override the prop with the same name passed to Provider. @defaultValue 700 | number | ---- | False |
| disableHoverableContent | When `true`, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger. @defaultValue false | boolean | ---- | False |
TooltipPortal
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| container | Specify a container element to portal the content into. | HTMLElement | ---- | False |
| forceMount | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. | true | ---- | False |
TooltipProvider
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| delayDuration | The duration from when the pointer enters the trigger until the tooltip gets opened. @defaultValue 700 | number | ---- | False |
| skipDelayDuration | How much time a user has to enter another trigger without incurring a delay again. @defaultValue 300 | number | ---- | False |
| disableHoverableContent | When `true`, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger. @defaultValue false | boolean | ---- | False |
Tooltip
| Prop | Description | Type | Default | Required |
|---|
TooltipContent
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
| disabled | Prevent the tooltip from showing up | boolean | false | False |
| offsetSide | string | number | WPDSThemeSpaceObject | theme.space[025] | False | |
| side | "bottom" | "left" | "right" | "top" | top | False | |
| align | "center" | "end" | "start" | center | False | |
| offsetAlign | string | number | WPDSThemeSpaceObject | 0 | False | |
| forceMount | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. | true | ---- | False |
| aria-label | A more descriptive label for accessibility purpose | string | ---- | False |
| onEscapeKeyDown | Event handler called when the escape key is down. Can be prevented. | (event: KeyboardEvent) => void | ---- | False |
| onPointerDownOutside | Event handler called when the a `pointerdown` event happens outside of the `Tooltip`. Can be prevented. | (event: PointerDownOutsideEvent) => void | ---- | False |
| asChild | boolean | ---- | False | |
| sticky | "always" | "partial" | ---- | False | |
| sideOffset | number | ---- | False | |
| alignOffset | number | ---- | False | |
| arrowPadding | number | ---- | False | |
| avoidCollisions | boolean | ---- | False | |
| collisionBoundary | Element | Element[] | ---- | False | |
| collisionPadding | number | Partial<Record<"bottom" | "left" | "right" | "top", number>> | ---- | False | |
| hideWhenDetached | boolean | ---- | False | |
| updatePositionStrategy | "always" | "optimized" | ---- | False | |
| density | Specify the amount of padding for the inner components. | "default" | "compact" | ({ "@sm"?: "default" | "compact"; "@md"?: "default" | "compact"; "@lg"?: "default" | "compact"; "@xl"?: "default" | "compact"; "@xxl"?: "default" | "compact"; "@notSm"?: "default" | "compact"; ... 18 more ...; "@initial"?: "default" | "compact"; } & { ...; }) | ---- | False |
TooltipTrigger
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
| asChild | boolean | ---- | False |