@neovici/cosmoz-tooltip

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 name@domain.com"
></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