Tooltip

Due to accessibility reasons with aria-describedby, the tooltip must be the same document / shadowRoot as the item being described by the tooltip.

Tooltips are intended for re-use and are close to how you would make a native tooltip.

Generally, the 2 things you want to pass to the tooltip are var(--background) and var(--border-color). Let’s see what that looks like in action:

API Reference

Imports

Script

HTML

<!-- Auto registers as <role-tooltip> -->
<script type="module" src="https://cdn.jsdelivr.net/npm/role-components/exports/tooltip/tooltip-register.js"></script>

CDN

HTML

<script type="module">
  // Auto registers as <role-tooltip>
  import "https://cdn.jsdelivr.net/npm/role-components/exports/tooltip/tooltip-register.js"

  // Manual Register
  import RoleTooltip from "https://cdn.jsdelivr.net/npm/role-components/exports/tooltip/tooltip.js"
  RoleTooltip.define()
  // => Registers as <role-tooltip>
</script>

Bundler

JavaScript

// Auto registers as <role-tooltip>
import "role-components/exports/tooltip/tooltip-register.js"

// Manual Register
import RoleTooltip "role-components/exports/tooltip/tooltip.js"
RoleTooltip.define()
// => Registers as <role-tooltip>

Slots

Name	Description
	default slot

Attributes

Name	Description	Type	Default
[Attribute + Property] `popover`	A popover attribute can have values “auto” (default) or “manual”. Popovers that have the auto state can be “light dismissed” by selecting outside the popover area, and generally only allow one popover to be displayed on-screen at a time. By contrast, manual popovers must always be explicitly hidden, but allow for use cases such as nested popovers in menus	`"auto" \| "manual"`	`"manual"`
[Attribute + Property] `role`	The “role” attribute. Default is “tooltip” and generally shouldn’t be overriden.	`string`	`"tooltip"`
[Attribute + Property] `arrow`	Attaches an arrow to the popover. The arrow’s size and color can be customized using the `--arrow-size` and `--background-color` custom properties. For additional customizations, you can also target the arrow using `::part(arrow)` in your stylesheet.	`boolean`	`true`
[Attribute + Property] `distance`	The distance in pixels from which to offset along the “main axis”. Usually its equivalent to offsetY	`number`	`10`
[Attribute + Property] `placement`	The preferred placement of the popover. Note that the actual placement will vary as configured to keep the panel inside of the viewport.	`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'right' \| 'right-start' \| 'right-end' \| 'left' \| 'left-start' \| 'left-end'`	-
[Attribute] `current-placement` [Property] `currentPlacement`	The `currentPlacement` property / `current-placement` attribute are where Floating UI actually positions the popup.	`this["placement"] \| null`	-
[Attribute + Property] `strategy`	Determines how the popover is positioned. Because you native “popover” API uses a fixed strategy, we use it as the default.	`Strategy`	-
[Attribute + Property] `skidding`	The distance in pixels from which to offset along the “cross axis”. Usually its equivalent to offsetX.	`number`	-
[Attribute] `arrow-placement` [Property] `arrowPlacement`	The placement of the arrow. The default is `anchor`, which will align the arrow as close to the center of the anchor as possible, considering available space and `arrow-padding`. A value of `start`, `end`, or `center` will align the arrow to the start, end, or center of the popover instead.	`'start' \| 'end' \| 'center' \| 'anchor'`	-
[Attribute] `arrow-padding` [Property] `arrowPadding`	The amount of padding between the arrow and the edges of the popover. If the popover has a border-radius, for example, this will prevent it from overflowing the corners.	`number`	-
[Attribute + Property] `flip`	When set, placement of the popover will flip to the opposite site to keep it in view. You can use `flipFallbackPlacements` to further configure how the fallback placement is determined.	`boolean`	-
[Attribute] `flip-fallback-placements` [Property] `flipFallbackPlacements`	If the preferred placement doesn’t fit, popover will be tested in these fallback placements until one fits. Must be a string of any number of placements separated by a space, e.g. “top bottom left”. If no placement fits, the flip fallback strategy will be used instead.	`string`	-
[Attribute] `flip-fallback-strategy` [Property] `flipFallbackStrategy`	When neither the preferred placement nor the fallback placements fit, this value will be used to determine whether the popover should be positioned using the best available fit based on available space or as it was initially preferred.	`'best-fit' \| 'initial'`	-
[Attribute] `flip-padding` [Property] `flipPadding`	The amount of padding, in pixels, to exceed before the flip behavior will occur.	`number`	-
[Attribute + Property] `shift`	Moves the popover along the axis to keep it in view when clipped.	`boolean`	-
[Attribute] `shift-padding` [Property] `shiftPadding`	The amount of padding, in pixels, to exceed before the shift behavior will occur.	`number`	-
[Attribute] `auto-size` [Property] `autoSize`	When set, this will cause the popover to automatically resize itself to prevent it from overflowing.	`null \| 'horizontal' \| 'vertical' \| 'both'`	-
[Attribute + Property] `sync`	Syncs the popover’s width or height to that of the anchor element.	`null \| 'width' \| 'height' \| 'both'`	-
[Attribute] `auto-size-padding` [Property] `autoSizePadding`	The amount of padding, in pixels, to exceed before the auto-size behavior will occur.	`number`	-
[Attribute] `hover-bridge` [Property] `hoverBridge`	When a gap exists between the anchor and the popover element, this option will add a “hover bridge” that fills the gap using an invisible element. This makes listening for events such as `mouseenter` and `mouseleave` more sane because the pointer never technically leaves the element. The hover bridge will only be drawn when the popover is active.	`boolean`	-

Functions

Name	Description	Parameters
`handlePopoverTriggerEvent()`	-	`e: RoleTooltipToggle`
`handleReposition()`	-	-
`handleKeyDown()`	-	`e: KeyboardEvent`
`handleFocusChange()`	This is a hack. Unfortunately, there’s no reliable way to get the active elements from just “focusin” / “focusout”	-
`handleShow()`	Used to show from event listeners.	`event: Event`
`show()`	-	`triggerElement: Element, triggerSource: RoleTooltip["__triggerSource"]`
`findTriggerForTooltip()`	-	`e: Event`
`handleHide()`	-	`event: Event`
`hide()`	-	`triggerSource: null \| RoleTooltip["__triggerSource"]`
`debounce()`	-	`callback: (...args: any[]) => any, options: { key: any, wait: number }`

Parts

Name	Description
`popover`	-
`popover--active`	-
`popover--fixed`	-
`popover--has-arrow`	-
`arrow`	-
`hover-bridge`	-
`hover-bridge--visible`	-

Toolbar