Usage
Tooltip is a floating container that displays additional information for the element a user hovers or focuses. Use it for short hints — such as describing an icon-only button or surfacing a keyboard shortcut — not for essential content.
A tooltip is wired to its trigger through id: give the tooltip an id, then point the trigger's aria-describedby at it. The tooltip then shows on hover and focus, and hides on blur or Esc.
import "@nordhealth/components/lib/Tooltip"
Place the trigger and the tooltip together, linking them by id:
Examples
Position
The position attribute places the tooltip relative to its trigger: block-start (above, the default), block-end (below), inline-start, or inline-end.
Shortcut keys
Use the shortcut slot to display the keyboard shortcut that activates the subject, alongside the tooltip text.
Shared across triggers
A single tooltip can be reused by several triggers — point each trigger's aria-describedby at the same tooltip id. This is handy for repeated row actions in a Table.
Multiple triggers in a table
A practical application of shared triggers: each row's action button in a Table points at the same tooltip id via aria-describedby, so one tooltip serves every row.
Custom size
Control the maximum width of the tooltip with the --n-tooltip-max-size custom property when the default is too wide or too narrow for your content.
RTL
The tooltip follows the document or container direction, mirroring its inline positioning. Toggle the direction to see it flip.
Accessibility
- Connect the tooltip to its trigger by setting
aria-describedbyon the trigger to the tooltip'sid. This gives the trigger an accessible description and lets the tooltip appear on both hover and keyboard focus. - Tooltips are supplementary — never put essential information or interactive controls inside one, because they are not always reachable and dismiss on blur.
- The tooltip can be dismissed with the Esc key, and it escapes to the top layer via the Popover API so it is never clipped by ancestors with
overflow: hiddenorcontainer-type.
API reference
Tooltip
Tooltips are floating containers for displaying additional information for the currently focused element. A tooltip can be useful when you want to e.g. give a hint about an existing Command Menu shortcut.
<nord-tooltip></nord-tooltip>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
position | position | Control the position of the tooltip component. When set to "none", the tooltip will be shown above but accommodate for browser boundaries. | 'block-end' | 'block-start' | 'inline-start' | 'inline-end' | 'block-start' |
role | role | The tooltip role, set on the component by default. | string | 'tooltip' |
id | id | The id for the active element to reference via aria-describedby. | string | '' |
delay | delay | The delay in milliseconds before the tooltip is opened. | number | 500 |
open | open | Indicates whether the tooltip is currently open. | boolean | false |
sideOffset | side-offset | Distance in pixels from the trigger along the main axis — the gap between
the tooltip and the side it opens against. Fed into Floating UI's offset
middleware as mainAxis. Defaults to 8. | number | 8 |
alignOffset | align-offset | Offset in pixels along the alignment axis — skids the tooltip along the
trigger's edge. Fed into Floating UI's offset middleware as
alignmentAxis. Defaults to 0. | number | 0 |
Slots
| Slot name | Description |
|---|---|
Default slot | The tooltip content |
shortcut | Optional slot that holds shortcut keys to access the subject |
CSS Properties
CSS Custom Properties provide more fine grain control over component presentation. We advise utilizing existing properties on the component before using these.
| Property | Description | Default |
|---|---|---|
--n-tooltip-max-size | Controls the maximum inline size, or width, of the tooltip. | 50ch |
Design guidelinesFor designers
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
Do
- Use a tooltip if an interactive element requires more explanation.
- Use a tooltip to provide additional information, such as UI shortcuts.
- Use the
labelattribute on icons used for shortcuts for accessibility. - Use clear and accurate phrasing.
- Be consistent with positioning of tooltips in the user interface.
Don’t
- Don’t use interactive elements such as links or buttons inside a tooltip.
- Don’t rely on tooltips when you have room to provide more explanation.
- Don’t depend on tooltips for vital information.
Content guidelines
Tooltips should be clear and informative, but not imperative to using the interface they refer to. They should not contain interactive elements such as buttons or links.
Tooltips should provide useful information and not repeat information that is already present.
When writing tooltips, always write them in sentence case, not title case. The first word should be capitalized and the rest lowercase (unless a proper noun):
Use tooltips sparingly. If your UI is requiring a lot of tooltips, consider revising the interface to provide better explanations and better labelling.
Additional considerations
- Always provide a tooltip for icon-only buttons or a button with an associated keyboard shortcut.
- Don’t use tooltip to communicate critical information, including errors.
- Use sparingly. If you’re building something that requires a lot of tooltips, take a step back and work on clarifying the design and the language used instead.