selection-popover

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

selection-popover

★ 64 Open GitHub ↗

Easy-to-use, unstyled, composable react selection popover.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  Easy-to-use, composable react selection popover
</p>

<a href="https://www.npmjs.com/package/selection-popover">![npm version](https://img.shields.io/npm/v/selection-popover.svg)</a>
<a href="https://www.npmjs.com/package/selection-popover">![npm downloads](https://img.shields.io/npm/dm/selection-popover.svg)</a>

</div>

## Install

```bash
npm install selection-popover
```

## Content

- [Anatomy](#anatomy)
- [API Reference](#api-reference)
  - [Root](#root)
  - [Trigger](#trigger)
  - [Portal](#portal)
  - [Content](#content)
  - [Arrow](#arrow)
- [Examples](#examples)
  - [Origin-aware animations](#origin-aware-animations)
  - [Collision-aware animations](#collision-aware-animations)
  - [Unmount animations](#unmount-animations)
  - [Use with Radix Toolbar](#use-with-radix-toolbar)
- [Acknowledgements](#acknowledgements)

## Anatomy

Import all parts and piece them together.

```jsx
import * as Selection from 'selection-popover'

export default () => (
  <Selection.Root>
    <Selection.Trigger />
    <Selection.Portal>
      <Selection.Content>
        <Selection.Arrow />
      </Selection.Content>
    </Selection.Portal>
  </Selection.Root>
)
```

## API Reference

### Root

Contains all the parts of a selection.

| Prop           | Type                      | Default | Description                                                                                                         |
| -------------- | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `defaultOpen`  | `boolean`                 | -       | The open state of the hover card when it is initially rendered. Use when you do not need to control its open state. |
| `open`         | `boolean`                 | -       | The controlled open state of the popover. Must be used in conjunction with `onOpenChange`.                          |
| `onOpenChange` | `(open: boolean) => void` | -       | Event handler called when the open state of the popover changes.                                                    |
| `whileSelect`  | `boolean`                 | `false` | When `true`, the popover will open while the text is selected, otherwise only when the mouse up.                    |
| `disabled`     | `boolean`                 | `false` | When true, the popover won't open when text is selected.                                                            |
| `openDelay`    | `number`                  | `0`     | The duration from when release the mouse until the content opens. In `whileSelect` is when you start the selection. |
| `closeDelay`   | `number`                  | `0`     | The duration from when you click outside of the content until the content closes.                                   |

### Trigger

The area that opens the popover. Wrap it around the target you want the popover to open when a text is selected.

### Portal

When used, portals the content part into the `body`.

| Prop         | Type          | Default         | Description                                                                                                                                                                              |
| ------------ | ------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean`     | -               | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. If used on this part, it will be inherited by `Selection.Content`. |
| `container`  | `HTMLElement` | `document.body` | Specify a container element to portal the content into.                                                                                                                                  |

### Content

The component that pops out when a text is selected.

| Prop                   | Type                                                            | Default   | Description                                                                                                                                                                                                               |
| ---------------------- | --------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asChild`              | `boolean`                                                       | false     | Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.             |
| `forceMount`           | `boolean`                                                       | -         | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. It inherits from `Selection.Portal`.                                                                |
| `side`                 | `"top" \| "right" \| "bottom" \| "left"`                        | `top`     | The preferred side of the selection to render against when open. Will be reversed when collisions occur and `avoidCollisions` is enabled.                                                                                 |
| `sideOffset`           | `number`                                                        | `0`       | The distance in pixels from the selection.                                                                                                                                                                                |
| `align`                | `"start" \| "center" \| "end"`                                  | `center`  | The preferred alignment against the selection. May change when collisions occur.                                                                                                                                          |
| `alignOffset`          | `number`                                                        | `0`       | An offset in pixels from the `"start"` or `"end"` alignment options.                                                                                                                                                      |
| `avoidCollisions`      | `boolean`                                                       | `true`    | When `true`, overrides the `side` and `align` preferences to prevent collisions with boundary edges.                                                                                                                      |
| `collisionBoundary`    | `Element \| null \| Array<Element \| null>`                     | `[]`      | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check.                                                                   |
| `collisionPadding`     | `number \| Partial<Record<Side, number>>`                       | `0`       | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: `{ top: 20, left: 20 }`.                          |
| `arrowPadding`         | `number`                                                        | `0`       | The padding between the arrow and the edges of the content. If your content has `border-radius`, this will prevent it from overflowing the corners.                                                                       |
| `sticky`               | `"partial" \| "always"`                                         | `partial` | The sticky behavior on the align axis. `"partial"` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `"always"` will keep the content in the boundary regardless. |
| `hideWhenDetached`     | `boolean`                                                       | `false`   | Whether to hide the content when the text becomes fully occluded.                                                                                                                                                         |
| `onEscapeKeyDown`      | `(event: KeyboardEvent) => void`                                | -         | Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`.                                                                                                                  |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void`                      | -         | Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`.                                                                              |
| `onFocusOutside`       | `(event: FocusOutsideEvent) => void`                            | -         | Event handler called when focus moves outside the bounds of the component. It can be prevented by calling `event.preventDefault`.                                                                                         |
| `onInteractOutside`    | `(event: PointerDownOutsideEvent \| FocusOutsideEvent) => void` | -         | Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling `event.preventDefault`.                                                     |

| Data Attribute | Values                                   |
| -------------- | ---------------------------------------- |
| `[data-state]` | `"open" \| "closed"`                     |
| `[data-side]`  | `"left" \| "right" \| "bottom" \| "top"` |
| `[data-align]` | `"start" \| "end" \| "center"`           |

| CSS Variable                                   | Description                                                                   |
| ---------------------------------------------- | ----------------------------------------------------------------------------- |
| `--selection-popover-content-transform-origin` | The `transform-origin` computed from the content and arrow positions/offsets. |
| `--selection-popover-select-width`             | The width of the select.                                                      |
| `--selection-popover-select-height`            | The height of the select.                                                     |

### Arrow

An optional arrow element to render alongside the popover. This can be used to help visually link the selected text with the `Selection.Content`. Must be rendered inside `Selection.Content`.

| Prop      | Type      | Default | Description                                                                                                                                                                                                   |
| --------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | `false` | Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. |
| `width`   | `number`  | `10`    | The width of the arrow in pixels.                                                                                                                                                                             |
| `height`  | `number`  | `5`     | The height of the arrow in pixels.                                                                                                                                                                            |

## Examples

### Origin-aware animations

```jsx
// index.jsx
import * as Selection from 'selection-popover'
import './styles.css'

export default () => (
  <Selection.Root>
    <Selection.Trigger>...</Selection.Trigger>
    <Selection.Portal>
      <Selection.Content className="SelectionContent">...</Selection.Content>
    </Selection.Portal>
  </Selection.Root>
)
```

```css
/* styles.css */
.SelectionContent {
  transform-origin: var(--selection-popover-content-transform-origin);
  animation: scaleIn 500ms cubic-bezier(0.16, 1, 0.3, 1);
}

@keyframes scaleIn {
  from {
    opacity: 0;
    transform: scale(0);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}
```

### Collision-aware animations

```jsx
// index.jsx
import * as Selection from 'selection-popover'
import './styles.css'

```css
/* styles.css */
.SelectionContent {
  animation-duration: 400ms;
  animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
}
.SelectionContent[data-state='open'][data-side='top'] {
  animation-name: slideDownAndFade;
}
.SelectionContent[data-state='open'][data-side='bottom'] {
  animation-name: slideUpAndFade;
}

@keyframes slideDownAndFade {
  from {
    opacity: 0;
    transform: translateY(-2px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

@keyframes slideUpAndFade {
  from {
    opacity: 0;
    transform: translateY(2px));
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}
```

### Unmount animations

```jsx
// index.jsx
import * as Selection from 'selection-popover'
import './styles.css'

```css
/* styles.css */
.SelectionContent {
  animation-duration: 400ms;
  animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
}
.SelectionContent[data-state='open'] {
  animation-name: slideDownAndFade;
}
.SelectionContent[data-state='closed'] {
  animation-name: slideUpAndFade;
}

@keyframes slideDownAndFade {
  from {
    opacity: 0;
    transform: translateY(-2px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

@keyframes slideUpAndFade {
  from {
    opacity: 1;
    transform: translateY(0));
  }
  to {
    opacity: 0;
    transform: translateY(-2px);
  }
}
```

### Use with [Radix Toolbar](https://www.radix-ui.com/docs/primitives/components/toolbar)

```jsx
import * as Selection from 'selection-popover'
import * as Toolbar from '@radix-ui/react-toolbar'

export default () => (
  <Selection.Root>
    <Selection.Trigger>...</Selection.Trigger>
    <Selection.Portal>
      <Selection.Content asChild>
        <Toolbar.Root>...</Toolbar.Root>
        <Selection.Arrow />
      </Selection.Content>
    </Selection.Portal>
  </Selection.Root>
)
```

## Acknowledgements

- API heavily inspired on [Radix UI](https://www.radix-ui.com/)
- Inspired by this [tweet](https://twitter.com/TobiasWhetton/status/1612821266242715648) from [Tobias Whetton](https://twitter.com/TobiasWhetton)

selection-popover

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README