Migrating from v1

v2 changes how offsets, positioning, and ARIA attributes work. This page lists each change and how to update your code.

npm i @omsimos/react-highlight-popover@2

Breaking changesCopy Anchor Link

React 18 or laterCopy Anchor Link

v2 drops support for React 17.

Offset directionCopy Anchor Link

A positive offset.y now moves the popover away from the selection. In v1, it moved the popover up. Flip the sign:

- <HighlightPopover offset={{ y: -10 }} renderPopover={renderPopover}>
+ <HighlightPopover offset={{ y: 10 }} renderPopover={renderPopover}>

offset.x now always moves the popover right. In v1, it moved left with alignment="right".

PositionCopy Anchor Link

position is now the popover's top-left corner. In v1, it was the anchor point under the selection, and a CSS transform centered the popover.

Showing the popoverCopy Anchor Link

The popover now waits until the user releases the mouse. Add showWhileSelecting to keep the v1 behavior.

onSelectionStart now fires when a selection begins, before onSelectionEnd. In v1, it fired together with onPopoverShow.

ARIA attributesCopy Anchor Link

The popover no longer has role="tooltip" and aria-live="polite". Pass them with popoverProps if you need them. See Accessibility.

Package outputCopy Anchor Link

The build output is now dist/index.mjs. Import from the package name, because deep imports into dist will break.

New defaultsCopy Anchor Link

v2 turns on two behaviors by default:

• Collision handling. The popover flips and shifts to stay in the viewport. Set avoidCollisions={false} to turn this off.
• Escape to dismiss. Set closeOnEscape={false} to turn this off.

New featuresCopy Anchor Link

• placement, collisionPadding, portal, and popoverProps props
• range and placement in renderPopover, and selectionRange and placement in useHighlightPopover
• A data-placement attribute on the popover element
• The popover follows the selection on scroll, resize, and reflow
• The package exports its types
• "use client" for Server Components