Popover

A popover is a floating content container that appears relative to a trigger element. Popovers display richer, persistent content that requires explicit user interaction (click or tap), while tooltips appear automatically on hover or focus with brief, contextual information.

Tooltip and Popover share the same component base. Both display contextual information, but their behaviour and purpose differ.

Tooltip: Short contextual hints that appear on hover or focus, and disappear automatically.
Popover: Persistent overlays that provide extra information or actions, such as links or preferences.

Both components follow the same tokenised structure for colours, spacing, and elevation to ensure consistency across brands and devices.

When to use it (and when not to)

Use a Tooltip when:

You need to provide brief, contextual information about an element.
The information helps clarify a label, icon, or control without interrupting the flow.
The content is short, non-essential, and disappears automatically after focus or hover ends.

Use a Popover when:

You need to display additional information, options, or actions that require user interaction.
The content is richer (e.g. includes title, link, or button) and must persist until dismissed.
The user needs time to read or interact with the content before closing it.

Avoid using both when:

The content is critical to complete a task — use a modal instead.
The message is too long to be displayed in a small floating container.
The user might miss the message due to automatic disappearance or poor trigger placement.

Quick summary of accessibility & consistency

Both Tooltip and Popover must comply with WCAG 2.1 (1.4.3, 1.4.13, 2.1.1) and EN 301 549 standards.
Ensure a minimum contrast ratio of 4.5:1 between text and background.
Tooltip: Triggered by hover or focus, dismissed on blur or Escape. Must be accessible via keyboard and announced using aria-describedby.
Popover: Triggered by click or tap, dismissed via close button, external click, or Escape. Browser-managed focus: the popover is inserted into the tab order after the trigger, and focus returns to the trigger on close. Include aria-labelledby when a title is present.
Always position the pointer or arrow so it clearly references the triggering element.
Maintain consistent spacing and elevation across brands and viewports.

Properties

Anatomy

Tooltip-Popover

Background blur:

Bg Blur/Bg blur 30 (30px)

Background elevation: Elevation/M

Bubble

Width: 343

Background color: #000000, 55%

Border color: #FFFFFF

Stroke alignment: Outside

Border weight: 1

Border radius: 4

Title (Optional)

Text color: #FBFBFC

Font family: Toyota Type

Font weight: Regular

Font size: 22

Line height: 32

Icon Button (Optional)

Depends on: Icon Button

Type: Filled

State: Neutral

Size: SM

Mode: On Dark

Slot

Depends on: slot

Link (Optional)

Depends on: Link

Icon: <Instance name>

Type: Inline

Size: Small

State: Rested

Leading icon: False

Trailing icon: False

Arrow

Height: 6

Width: 20

Border color: #FFFFFF

Border weight: 1

Background color: #000000, 55%

Background blur:

C-HR/C-HR BG Blur (30px)

The Tooltip variant supports arrow placement in four directions. It does not include a close button or link.

Top

Tooltip-Popover

Top: true

Bottom: false

Left: false

Right: false

Close Button: false

Link: false

Contrast: True

Left

Tooltip-Popover

Top: false

Bottom: false

Left: true

Right: false

Close Button: false

Link: false

Contrast: True

The component includes two visual variants to ensure legibility across different background contexts.

Contrast (True)

Tooltip-Popover

Contrast: True

Background: #1A1A1A

Text colour: #FFFFFF

Contrast (False)

Tooltip-Popover

Contrast: False

Background: #FFFFFF

Text colour: #1A1A1A

Both variants share identical behaviour, spacing, and accessibility rules. Use the Contrast (True) variant by default. Use the Contrast (False) variant when the component appears on dark backgrounds or over elements where higher contrast is required for readability and WCAG 2.1 AA compliance.

Modes

Toyota

Tooltip-Popover

Mode: Default

Lexus

Tooltip-Popover

Mode: Default

Minimum touch area

The Tooltip–Popover itself is not a directly interactive component. However, interactive elements inside it must respect the system’s minimum touch area standards:

Icon Button: Minimum 44×44 px (EN 301 549 / WCAG 2.5.5 Level AA)
Link / Text Link: Must remain fully focusable and tappable across devices

Composition

Layout and spacing

Bubble

Padding top: 16

Padding right: 16

Padding bottom: 20

Padding left: 16

Item spacing: 16

Bottom Content

Item spacing: 8

Width behaviour

Tooltip and Popover components use vertical auto layout with responsive width behaviour.

The main container (Bubble) resizes with hug contents.
A min-width of 150px ensures legibility for short tooltips or labels.
A max-width of 320px prevents excessively long lines and improves readability.
Text should wrap within these constraints and never be truncated or scroll horizontally.
These values ensure optimal legibility, responsive resizing, and support for localisation (e.g. longer words in German or Finnish).

Styling

Colors

Name	Applied as	Applied to
`color-surface-neutral-default`	Background color	Bubble (Neutral)
`color-surface-neutral-default`	Background color	Bubble (Neutral)
`color-surface-dim-neutral-subtle`	Background color	Bubble (Contrast)
`color-surface-dim-neutral-subtle`	Background color	Bubble (Contrast)
`color-foreground-neutral-emphasis`	Text color	Content (Neutral)
`color-foreground-neutral-emphasis`	Text color	Content (Neutral)
`color-border-contrast-emphasis`	Border color / Text color	Bubble (Contrast)
`color-border-contrast-emphasis`	Border color / Text color	Bubble (Contrast)
`color-surface-dim-neutral-default`	Backdrop color	Backdrop
`color-surface-dim-neutral-default`	Backdrop color	Backdrop

Spacing

Name	Applied as	Applied to
`spacing-xl`	Padding top / left / right	Bubble
`spacing-xl`	Padding top / left / right	Bubble
`spacing-2xl`	Padding bottom	Bubble
`spacing-2xl`	Padding bottom	Bubble
`spacing-xl`	Margin bottom	Title
`spacing-xl`	Margin bottom	Title
`spacing-sm`	Margin top	Link
`spacing-sm`	Margin top	Link

Other tokens

Name	Applied as	Applied to
`radius-sm`	Border radius	Bubble
`radius-sm`	Border radius	Bubble
`stroke-sm`	Border weight	Bubble (Neutral / Contrast)
`stroke-sm`	Border weight	Bubble (Neutral / Contrast)

Usage

Best Practices

Guidance on where this component has been used

Use Tooltips for short, non-interactive explanations triggered on hover or focus.
Use Popovers for extended or actionable content (such as links, settings, or preferences).
Avoid using Tooltips on mobile. They are not reliable on touch devices and should be replaced by inline text or contextual help patterns.
Replace Popovers with a Bottom Sheet (Modal) on mobile to maintain accessibility and usability on touch interfaces.
Do not include interactive elements inside Tooltips. Tooltips are purely informative and must disappear when focus or hover is lost.
Ensure clear close and dismissal actions for Popovers, with proper focus management and keyboard accessibility.

Responsive Behaviour

Guidance on where this component has been used

Use Popovers on desktop and tablet to display contextual or interactive content without leaving the current view.
On mobile, replace both with a Bottom Sheet (modal-style overlay) to ensure tactile accessibility and usability on touch screens.
The Bottom Sheet version keeps the same hierarchy and purpose but adapts the layout and interaction to smaller viewports.

Content / Copy Guidelines

Keep text short and precise, ideally one short sentence or phrase (max. 80–100 characters in English).
If the content exceeds the space, the text must wrap to a new line — never be truncated.
Avoid formatting, links, or interactive elements inside tooltips.
Use simple punctuation and sentence case.
Keep language easy to translate and consistent across markets.

Designed for longer content that may include short paragraphs, titles, or links.
Recommended length: up to 300–350 characters to maintain readability and accessibility across viewports.
If additional content is required, consider using a modal or side panel instead.
When text length expands in other languages, the popover should resize dynamically to accommodate the content without truncation or horizontal scroll.
Always check text wrapping behaviour in mobile and tablet layouts.

Internationalisation and readability

The component must adapt to longer languages by expanding vertically or horizontally when needed.
Avoid setting fixed heights for text areas.
Keep the same visual hierarchy (title > body > link) regardless of language or text length.

Styles

A popover is a floating content container that appears relative to a trigger element.

<div class="tng-popover">
  <div class="tng-popover-bubble">
    <p class="tng-text-body">…</p>
  </div>
</div>

Default
Contrast

Elements

Arrow

An arrow can be placed at top, right, bottom or left using the data-placement attribute.

<div class="tng-popover">
  <div class="tng-popover-arrow" data-placement="top"></div>
  <div class="tng-popover-bubble">
    <p class="tng-text-body">…</p>
  </div>
</div>

Default
Contrast

Backdrop

<div class="tng-backdrop"></div>
<div class="tng-popover">
  <div class="tng-popover-bubble">
    <p class="tng-text-body">…</p>
  </div>
</div>

Default
Contrast

Close button

<div class="tng-popover">
  <div class="tng-popover-bubble">
    <button class="tng-icon-button is-neutral" aria-label="Close">
      <i class="tng-icon icon-close" aria-hidden="true"></i>
    </button>
    <p class="tng-text-body">…</p>
  </div>
</div>

Default
Contrast

Title

<div class="tng-popover">
  <div class="tng-popover-bubble">
    <div class="tng-text-title">…</div>
    <p class="tng-text-body">…</p>
  </div>
</div>

Default
Contrast

Link

<div class="tng-popover">
  <div class="tng-popover-bubble">
    <p class="tng-text-body">…</p>
    <a class="tng-link">Link</a>
  </div>
</div>

Default
Contrast

Recipes

source code

React

The Popover is a provider component that displays rich interactive content when triggered by a click. Unlike tooltips which appear on hover, popovers require explicit user interaction to open and close.

This component must wrap PopoverTrigger and PopoverContent to function correctly.

Properties

Prop	Type	Description	Optional
`isContrast`	`boolean`	Choose between dark or light version of the popover	✅
`initialOpen`	`boolean`	Whether the popover is initially open, `false` by default	✅
`placement`	`Placement`	Position of the popover relative to trigger (`top`, `top-start`, `top-end` \| `bottom`, `bottom-start`, `bottom-end` \| `left`, `left-start`, `left-end` \| `right`, `right-start`, `right-end`). `top` by default	✅
`offset`	`number`	Distance in pixels between trigger and tooltip, defaults to 8px	✅

Example

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  IconButton,
} from '@tmedxp/react-components';

const PopoverExample = () => {
  return (
    <Popover placement="bottom" isContrast={false}>
      <PopoverTrigger>
        <IconButton iconName="info" size="sm" isNeutral />
      </PopoverTrigger>
      <PopoverContent title="More Information" labels={{ Close: 'Close' }}>
        <p>This is detailed interactive content.</p>
      </PopoverContent>
    </Popover>
  );
};

export { PopoverExample };

PopoverTrigger

The PopoverTrigger component wraps an element that opens the popover when clicked. It toggles the popover’s visibility on each click.

Must be used within a Popover provider.

The children of this component must be an interactable element (button, link,..)

Example

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  IconButton,
} from '@tmedxp/react-components';

const PopoverTriggerExample = () => {
  return (
    <Popover placement="right">
      <PopoverTrigger>
        <IconButton iconName="info" size="sm" isNeutral />
      </PopoverTrigger>
      <PopoverContent title="Details" labels={{ Close: 'Close popover' }}>
        Click the icon to toggle this popover
      </PopoverContent>
    </Popover>
  );
};

export { PopoverTriggerExample };

PopoverContent

The PopoverContent component displays interactive content in a panel. It includes a close button, optional title, optional link button, and can render as a modal on mobile devices.

Must be used within a Popover provider.

Properties

Prop	Type	Description	Optional
`labels`	`PopoverLabels`	Accessibility labels, requires `Close` property for close button	❌
`title`	`string`	Optional title displayed at the top of the popover	✅
`linkProperties`	`LinkButtonProperties`	Optional link button configuration displayed at the bottom	✅
`useModalOnMobile`	`boolean`	Renders as a modal on mobile devices, `false` by default	✅
`className`	`string`	Custom CSS class names for styling	✅

Example

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  IconButton,
} from '@tmedxp/react-components';

const PopoverContentExample = () => {
  return (
    <Popover placement="bottom">
      <PopoverTrigger>
        <IconButton iconName="info" size="sm" isNeutral />
      </PopoverTrigger>
      <PopoverContent
        title="Additional Information"
        linkProperties={{
          text: 'Learn More',
          href: '/more-info',
        }}
        useModalOnMobile={true}
        labels={{ Close: 'Close popover' }}
      >
        <p>This is detailed content with interactive elements.</p>
        <ul>
          <li>Feature 1</li>
          <li>Feature 2</li>
        </ul>
      </PopoverContent>
    </Popover>
  );
};

export { PopoverContentExample };

The Tooltip is a provider component that displays short contextual hints on hover or focus. It manages the state and positioning of tooltips, ensuring proper coordination between the trigger element and tooltip content.

This component must wrap TooltipTrigger and TooltipContent to function correctly.

Properties

Prop	Type	Description	Optional
`isContrast`	`boolean`	Choose between dark or light version of the tooltip	✅
`initialOpen`	`boolean`	Whether the tooltip is initially open, `false` by default	✅
`placement`	`Placement`	Position of the tooltip relative to trigger (`top`, `top-start`, `top-end` \| `bottom`, `bottom-start`, `bottom-end` \| `left`, `left-start`, `left-end` \| `right`, `right-start`, `right-end`). `top` by default	✅
`offset`	`number`	Distance in pixels between trigger and tooltip, defaults to 8px	✅

Example

import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  IconButton,
} from '@tmedxp/react-components';

const TooltipExample = () => {
  return (
    <Tooltip placement="top" isContrast={false}>
      <TooltipTrigger>
        <IconButton iconName="info" size="sm" isNeutral />
      </TooltipTrigger>
      <TooltipContent>This is helpful information</TooltipContent>
    </Tooltip>
  );
};

export { TooltipExample };

TooltipTrigger

The TooltipTrigger component wraps an element that triggers the tooltip display. When the user hovers over or focuses on this element, the associated tooltip content appears.

Must be used within a Tooltip provider.

The children of this component must be an interactable element (button, link,…)

Example

import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  IconButton,
} from '@tmedxp/react-components';

const TooltipTriggerExample = () => {
  return (
    <Tooltip placement="top">
      <TooltipTrigger>
        <IconButton iconName="info" size="sm" isNeutral />
      </TooltipTrigger>
      <TooltipContent>Helpful information appears here</TooltipContent>
    </Tooltip>
  );
};

export { TooltipTriggerExample };

TooltipContent

The TooltipContent component displays the actual content of the tooltip. It appears in a floating bubble with an arrow pointing to the trigger element. The content automatically positions itself relative to the trigger and viewport.

Must be used within a Tooltip provider.

Properties

TooltipContentProperties extends HTMLProps<HTMLElement> which means it includes all standard HTML element attributes.

Prop	Type	Description	Optional
`className`	`string`	Custom CSS class names for styling	✅

Example

import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  IconButton,
} from '@tmedxp/react-components';

const TooltipContentExample = () => {
  return (
    <Tooltip placement="bottom" isContrast={true}>
      <TooltipTrigger>
        <IconButton iconName="help" size="sm" isNeutral />
      </TooltipTrigger>
      <TooltipContent className="custom-tooltip">
        <p>This is detailed information that helps the user.</p>
        <p>It can contain multiple elements.</p>
      </TooltipContent>
    </Tooltip>
  );
};

export { TooltipContentExample };

useTooltipContext hook

The useTooltipContext hook provides access to the tooltip context, allowing child components to interact with the tooltip state and positioning. This hook must be used within a Tooltip or Popover provider component.

Returns

The hook returns an object with the following properties:

Property	Type	Description
`open`	`boolean`	Current open/closed state of the tooltip
`setOpen`	`(open: boolean) => void`	Function to programmatically open or close the tooltip

Usage

This hook is primarily used internally by TooltipTrigger, TooltipContent, PopoverTrigger, and PopoverContent components but it can be used in custom components that need access to the tooltip state.

Example

import { useTooltipContext } from '@tmedxp/react-components';

const CustomText = () => {
  const { open } = useTooltipContext();
  return <p>Tooltip is {open ? 'open' : 'closed'}</p>;
};

const CustomComponent = () => {
  return (
    <Popover>
      <CustomText />
      <PopoverTrigger>
        <button>Toggle Tooltip</button>
      </PopoverTrigger>
      <PopoverContent>
        <span>Some text</span>
      </PopoverContent>
    </Popover>
  );
};

export { CustomTooltipComponent };

Quick summary

Both Tooltip and Popover must comply with WCAG 2.1 (1.4.3, 1.4.13, 2.1.1) and EN 301 549 standards.
Ensure a minimum contrast ratio of 4.5:1 between text and background.
Tooltip: Triggered by hover or focus, dismissed on blur or Escape. Must be accessible via keyboard and announced using aria-describedby.
Popover: Triggered by click or tap, dismissed via close button, external click, or Escape. Browser-managed focus: the popover is inserted into the tab order after the trigger, and focus returns to the trigger on close. Include aria-labelledby when a title is present.
Always position the pointer or arrow so it clearly references the triggering element.
Maintain consistent spacing and elevation across brands and viewports.

For designers

Ensure sufficient colour contrast between text, icons, and background (minimum ratio 4.5:1, WCAG 2.1 AA).
Both Tooltip and Popover must remain fully readable and dismissible across light and dark themes.
Tooltip text should not rely solely on colour or animation to convey meaning.
Maintain clear spacing between Tooltip or Popover and the triggering element.
Avoid placing interactive elements too close to the Tooltip or Popover to prevent focus traps.
Ensure consistent alignment, padding, and border radius according to tokenised structure.
Focus styles must remain visible and meet WCAG AA contrast requirements across all supported surfaces. Focus should be clearly distinguishable from hover.
Colour tokens used within the component should be semantic (e.g. color-foreground-neutral-default) rather than fixed values. This ensures the component adapts correctly to different themes or surfaces.

For developers

Tooltip and Popover must be fully accessible via keyboard.
Tooltips should appear on focus and hover, and dismiss on blur or Escape.
Popovers should rely on the native Popover API for focus management — the browser inserts the popover into the tab order after the trigger and restores focus to the trigger on close. Avoid implementing custom focus traps.
Use aria-describedby for tooltips and aria-labelledby or aria-controls for popovers when referencing content.
Decorative icons must be marked with aria-hidden="true".
Each interactive element inside a Popover must be reachable and operable via keyboard.
Ensure all instances are tested through automated accessibility tools (e.g. Axe, Lighthouse) before release.
Manually verify focus order and visibility in both themes to confirm expected behaviour.

Roles & attributes

Tooltips — use role="tooltip" and link them to their trigger with aria-describedby.
Popovers with interactive content — use role="dialog" (or role="alertdialog" when the user must acknowledge something). Link the trigger to the popover with aria-controls or use popovertarget.

The Popover API provides built-in accessibility benefits — including focus management, light-dismiss, and top-layer promotion — without custom JavaScript.

Attribute	Behaviour
`popover` (or `popover="auto"`)	Light-dismiss enabled. Opening one `auto` popover closes other open `auto` popovers (unless they are nested or ancestral).
`popover="manual"`	No light-dismiss. Must be closed explicitly via `popovertarget` or JavaScript.
`popover="hint"`	Light-dismiss enabled. Hint popovers do not close `auto` popovers — allowing a tooltip to appear while a menu or dialog popover is still open. Only one `hint` popover can be open at a time. Ideal for tooltips.

Keyboard interaction

Key	Action
`Tab`	Moves focus into and out of the popover. For `auto` and `hint` popovers the browser updates the tab order automatically.
`Escape`	Closes the popover (light-dismiss). When using `popover="manual"`, implement this yourself or use a `CloseWatcher`.

Screen readers

Always provide an accessible name. Use aria-label, aria-labelledby, or a visible title inside the popover bubble.
For tooltips, ensure the trigger has aria-describedby pointing to the tooltip’s id so the description is announced when the trigger receives focus.
For dialog popovers, set aria-expanded on the trigger to communicate the open / closed state.

Focus behaviour

The Tooltip appears when its trigger element receives focus or hover.
The Tooltip never receives focus itself — focus must always remain on the trigger element.
It disappears automatically when focus moves away, the element is blurred, or the user presses Escape.
When the trigger regains focus, the Tooltip reappears automatically to preserve context.
The focus indicator on the trigger must remain visible and clearly distinguishable while the Tooltip is active.
Tooltips must contain only short, non-interactive text. If the content requires links, buttons, or other actions, use a Popover instead.

Focus starts on the trigger element — The trigger element (e.g. a button, icon, or link with popovertarget) must receive focus first. The trigger must have a visible focus indicator.
When the popover opens — Focus stays on the trigger. The browser inserts the popover into the sequential focus navigation order so the next Tab moves into the popover content. The popover content must be associated with the trigger using aria-labelledby or aria-describedby.
While the popover is open — Tab moves through the focusable elements inside the popover. Pressing Tab past the last focusable element moves focus to the next focusable element after the trigger in document order, as if the popover were inline at that position — popovers are not focus-trapped. Pressing Escape closes the popover (light-dismiss). For popover="auto", clicking outside the popover also closes it.
When the popover closes — Focus returns to the original trigger element automatically. The trigger’s focus ring should remain visible.

Popover

When to use it (and when not to)

Quick summary of accessibility & consistency

Properties

Anatomy

States : Tooltip

Top

Left

Right

Bottom

States : Popover

Top

Left

Right

Bottom

Variants

Contrast (True)

Contrast (False)

Modes

Toyota

Lexus

Minimum touch area

Composition

Layout and spacing

Width behaviour

Styling

Colors

Spacing

Other tokens

Usage

Best Practices

Responsive Behaviour

Content / Copy Guidelines

Tooltip

Popover

Internationalisation and readability

Styles

Elements

Arrow

Backdrop

Close button

Title

Link

Recipes

Tooltip

Popover

React

Popover

Properties

Example

PopoverTrigger

Example

PopoverContent

Properties

Example

Tooltip

Properties

Example

TooltipTrigger

Example

TooltipContent

Properties

Example

useTooltipContext hook

Returns

Usage

Example

Quick summary

For designers

For developers

Roles & attributes

HTML Popover API

Keyboard interaction

Screen readers

Focus behaviour

Tooltip

Popover