react-text-selection-popover

This module provides a way to render a popover/tooltip style component when text (inside a contenteditable element) is selected.

Disclaimer

This only works inside an element with the contenteditable tag
This doesn't give you the selected text, use the Selection API

Install

npm install --save react-text-selection-popover

Usage

The simplest way to use react-text-selection-popover is with 0 props just like this:

<Popover><MySweetComponent /></Popover>

This will display the popover when any text on the page is selected.

Restricting selection to a component

By default, any text within document (or in other words - the entire page) will trigger the Popover. To restrict it you can define the selectionRef prop. Just pass a React ref to it:

constructor(props) {
  super(props)
  this.ref = React.createRef()
}

render() {
  return <div>
    <p ref={this.ref}>This text will trigger the popover</p>
    <Popover selectionRef={this.ref}>Hello there</Popover>
  </div>
}

Positioning the Popover

Since 1.0, positioning is completely configurable via the placementStrategy prop. By default, the popover gets centered above or below the text selection (useful for inline toolbars in text editors like Medium) but you're not tied in to this behaviour.

Alternative strategies are in the lib folder of the package.

Here's how you use a placement strategy from the lib folder:

import Popover from 'react-text-selection-popover';
import placeRightBelow from 'react-text-selection-popover/lib/placeRightBelow'

<Popover
  placementStrategy={placeRightBelow}
>
  <!-- my awesome popover content here -->
</Popover

Writing your own placement strategy

You can also write your very own placement strategy. A placement strategy takes as an argument an object containg all the properties you need to compute the position of the popover and returns a style object as a result. See below for the exact shape of the Object

If you'd like to look at an example, just have a look at the default positioning strategy

Btw: If you have written a placement strategy that you want to share because you think it might be useful to others :), please open a pr and add it to the lib folder. I'd be more than happy to review it and help get it merged if there's a significant usecase.

Managing Popover display

By default, the popover automatically opens when text is selected and closes when text is unselected. However, on some occasions you might want to control this yourself.

To control whether the Popover is shown or not all you need to define is the isOpen prop. isOpen={true} will show the popover, isOpen={false} will hide it.

<Popover isOpen={this.state.isOpen}>Hey there</Popover>

You might still want to use selection events to control whether the Popover is shown or hidden. To do so - use the onTextSelect and onTextUnSelect prop.

<Popover
  isOpen={this.state.isOpen}
  onTextSelect={() => this.setState({ isOpen: true })}
  onTextUnselect={() => this.setState({ isOpen: false })}
>Hey there</Popover>

Using Popover inside a scrollable element

Some applications have scrollable elements inside them other than <body>. By default Popover repositions itself when the viewport scrolls (window that is). If you're using the Popover inside a scrollable element you need to define the scrollRef prop like so:

class MyApp extends Component {
  constructor() {
    this.scrollRef = React.createRef()
  }

  render() {
    return <div>
      <main ref={this.scrollRef}>
      </main>
      <Popover scrollRef={this.scrollRef}>My popover</Popover>
    </div>
  }
}

For more info on how to use the Popover component, please see below :)

`<Popover />` Props

Property	Type	required?	Description
`containerNode`	`React.ref`	optional	DOM element where popover will be mounted (defaults to `document.body`)
`selectionRef`	`React.ref`	optional	Set this to constrain selection events to a dom element and its children. You need this especially if you use more than one Popover component (defaults to `document`)
`scrollRef`	`React.ref`	optional	By default Popover repositions itself when there's a scroll event for document.body. Set this to reposition the Popover upon scrolling of a given element
`isOpen`	`Boolean`	optional	Is the Popover visible or not (defaults to `true`)
`onTextSelect`	`Function`	optional	Callback for when text is selected (typically used for setting state that opens the modal)
`onTextUnSelect`	`Function`	optional	Callback for when selection collapses (typically used for setting state that closes the modal)
`className`	`String`	optional	CSS class name for Popover container.
`gap`	`Number`	optional	Pixel gap between text selection and popover - (defaults to `5`)
`placementStrategy`	`({ gap, windowWidth, windowHeight, topOffset, leftOffset, lineHeight, boxWidth, boxHeight }) => StyleObject`	optional	A method that produces a style object to position the popover

License

Shoutouts

This was originally written during some freelance work for Spectrum. Shoutout to their awesomeness for letting me do all my work for them in the open!

Work with me?

I freelance for clients around the world, hit me up on my website to get in touch about a project.

arjitj87 / react-text-selection-popover Goto Github PK