Warp Design System

Appearance

Tooltip - Elements ​

A tooltip is a message box that is displayed when a user hovers over or gives focus to a UI element.

AndroidreleasedElementsreleasediOSreleasedReactreleasedVuereleased

Accessibility ​

ARIA attribute ​

We use aria-labelledby instead of aria-describedby to create the relationship between the tooltip and its target.

The ARIA Authoring Practices Guide (APG) recommends aria-describedby, but at time of writing that must be set directly on the focusable element. Since w-button's focusable button element is inside a shadow root we can't set up that relationship. Cross-root references by ID is impossible and the related ARIA properties on the Element are read only.

We might revisit this design later should cross-root ARIA references become supported.

Usage ​

A tooltip is a message box that is displayed when a user hovers over or gives focus to a UI element.

Tooltips should be used sparingly and contain succinct, supplementary information.

html
<w-button id="my-button" aria-labelledby="my-tooltip">Hover over me</w-button>
<w-tooltip id="my-tooltip" for="my-button">I am a tooltip</w-tooltip>

Examples ​

By default the tooltip is placed above the target element if there is room. If there's no room above it flips side and is placed below the target.

html
<w-button id="basic-button" aria-labelledby="basic-tooltip">Hover over me</w-button>
<w-tooltip id="basic-tooltip" for="basic-button">I am a tooltip</w-tooltip>

Adjust placement ​

You can specify a different initial placement. If there's no room the tooltip flips to the opposite side of the target.

Available positions:

  • top (this is the default)
  • bottom
  • left
  • right
html
<w-button id="placed-button" aria-labelledby="placed-tooltip">Hover over me</w-button>
<w-tooltip id="placed-tooltip" for="placed-button" placement="right">I am a tooltip</w-tooltip>

Styling API ​

This component supports styling through component tokens (CSS custom properties with a --w-c- prefix) and parts.

Parts ​

Use ::part(...) from outside the component.

  • tooltip - the tooltip container with background color, padding etc.
  • arrow - a square container used for positioning the visual part of the arrow
  • beak - the visual part of the arrow pointing at the target
  • hover-bridge - an invisible element there to ensure the tooltip doesn't close when moving the cursor from the target to the tooltip

Example:

css
w-tooltip::part(tooltip) {
  text-transform: uppercase;
}

Component tokens ​

Set these on w-tooltip to override visuals.

css
w-tooltip {
    --w-c-tooltip-bg: lime;
    --w-c-tooltip-color: black;
}

Layout & typography ​

  • --w-c-tooltip-z-index

Background ​

  • --w-c-tooltip-bg

Text color ​

  • --w-c-tooltip-color
Shadow ​
  • --w-c-tooltip-box-shadow

<w-tooltip> API ​

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

Properties ​

NameTypeDefaultSummary
forstring""ID of the element that triggers the tooltip on hover or focus.
hide (JS only)hide() => void--
hide-delaynumber0Milliseconds to wait before hiding the tooltip on mouseout.
no-arrowbooleanfalseHide the arrow pointing toward the tooltip target.
openbooleanfalseIndicates whether the tooltip is visible or not.
placementTooltipPlacement"top"Sets the placement of the tooltip relative to its target.
show (JS only)show() => void--
show-delaynumber150Milliseconds to wait before showing the tooltip on hover.

Property Details ​

for ​

ID of the element that triggers the tooltip on hover or focus.

  • Type: string
  • Default: ""

hide (JS only) ​

  • Type: hide() => void
  • Default: -

hide-delay ​

Milliseconds to wait before hiding the tooltip on mouseout.

  • Type: number
  • Default: 0

no-arrow ​

Hide the arrow pointing toward the tooltip target.

  • Type: boolean
  • Default: false

open ​

Indicates whether the tooltip is visible or not.

  • Type: boolean
  • Default: false

placement ​

Sets the placement of the tooltip relative to its target.

The tooltip will try to position itself at the given placement. If there is no room it will flip to the opposite side automatically.

show (JS only) ​

  • Type: show() => void
  • Default: -

show-delay ​

Milliseconds to wait before showing the tooltip on hover.

Keep at a non-zero value to avoid flickering the tooltip on and off when cursors move quickly past the target element.

Focusing the target element shows the tooltip immediately.

  • Type: number
  • Default: 150

Types ​

TooltipPlacement ​

'top' | 'bottom' | 'left' | 'right'

Questions? ​

Feel free to ask any questions on usage in the Warp DS Slack channel: #warp-design-system