cosmoz-tooltip

Tooltip web component using modern CSS APIs (CSS Anchor Positioning, Popover API) built with @pionjs/pion.

Installation

npm install @neovici/cosmoz-tooltip

Usage

Wrapping mode

<script type="module">
	import '@neovici/cosmoz-tooltip';
</script>

<cosmoz-tooltip heading="Help" description="Click to submit the form">
	<button>Submit</button>
</cosmoz-tooltip>

For attribute mode

Target elements by their name attribute within the same document/shadow root:

<input name="email" type="email" />
<cosmoz-tooltip
	for="email"
	heading="Email format"
	description="Enter a valid email like [email protected]"
></cosmoz-tooltip>

Rich content (wrapping mode only)

<cosmoz-tooltip>
	<button>Info</button>
	<div slot="content">
		<strong>Custom HTML</strong>
		<ul>
			<li>First item</li>
			<li>Second item</li>
		</ul>
	</div>
</cosmoz-tooltip>

API

| Attribute | Type | Default | Description | | ------------- | ------- | ------- | ------------------------------------------------------------------------- | | heading | string | - | Bold heading text | | description | string | - | Secondary description text | | for | string | - | Target element's name attribute | | placement | string | top | Position: top, bottom, left, right, top center, bottom center | | delay | number | 300 | Delay before showing tooltip (ms) | | disabled | boolean | false | When present, prevents the tooltip from showing |

Slots

| Slot | Description | | --------- | -------------------------------------------------- | | (default) | Trigger element (wrapping mode) | | content | Rich HTML content for tooltip (wrapping mode only) |

Features

• CSS Anchor Positioning — tooltip automatically anchors to trigger element
• Popover API — proper layering without z-index hacks
• Automatic flip — repositions when constrained by viewport via position-try-fallbacks
• Smooth animations — uses @starting-style and allow-discrete transitions
• Non-blocking — pointer-events: none ensures tooltips never block interactions
• Keyboard accessible — shows on focus, hides on blur

Design decisions

No arrow/caret

CSS Anchor Positioning's position-try-fallbacks can flip the tooltip to the opposite side when constrained by the viewport. There is no pure CSS way to detect when a flip occurs, so an arrow's direction cannot reliably match the actual tooltip position.

No rich content in for="" mode

The for="" mode creates the popover in the light DOM (required for CSS Anchor Positioning to work across elements). Since there's no shadow boundary, slot projection isn't available — content is limited to heading and description attributes.

Browser support

This component uses CSS Anchor Positioning and Popover API, both Baseline 2026.

Development

npm install
npm run storybook:start  # Start Storybook on port 8000
npm test                 # Run tests
npm run build            # Build for production

License

Apache-2.0

Built with @pionjs/pion