Highlight Popover

Interaction

When the popover appears and what hides it.

Showing the popover

When the user selects with a mouse or pen, the popover appears after they release it. Set showWhileSelecting to show and update the popover during the drag instead.

showWhileSelecting=false

Drag slowly across this sentence and watch when the popover appears.

showWhileSelecting=true

Drag slowly across this sentence and watch when the popover appears.

Keyboard selections show the popover immediately. minSelectionLength sets the minimum number of characters, not counting whitespace at either end. An empty selection never shows the popover, even when minSelectionLength is 0.

Interacting with the popover

Clicking inside the popover keeps it open, so its buttons work even when the click clears the selection. Selecting text inside the popover doesn't move it.

Dismissing the popover

The popover hides when the selection becomes empty or moves outside the wrapper.

Pressing Escape also hides it, until the selection changes. Escape doesn't hide it while an input method editor (IME) is composing text, or when an element inside the popover already handled the key with event.preventDefault(), such as a dropdown that closes itself. Set closeOnEscape={false} to turn this off.

Controlling the popover

setShowPopover from useHighlightPopover shows or hides the popover. Hiding it works like Escape, so the popover stays hidden until the selection changes. Showing it needs a selection to anchor to, so setShowPopover(true) does nothing when no text is selected.

function Popover() {
  const { setShowPopover } = useHighlightPopover();

  return <button onClick={() => setShowPopover(false)}>Done</button>;
}

Callbacks

CallbackFires when
onSelectionStartA selection begins inside the wrapper
onSelectionEndA selection is complete. Receives the selected text
onPopoverShowThe popover appears
onPopoverHideThe popover is hidden, including on unmount

Callbacks can be inline functions. The component always calls the latest version, and a new function on each render doesn't fire extra callbacks.

On this page