useTextSelection

Reactively tracks the current text selection on the page. Listens to the selectionchange event and exposes the selected text, ranges, and bounding rectangles as observables.

rects$ is computed lazily — getBoundingClientRect() is only called when rects$ is actually accessed, avoiding unnecessary reflows when bounding rectangles are not needed.

Demo

Text Selection

Select any text on this page to see the selection details update in real time.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus lacinia odio vitae vestibulum vestibulum. Cras porttitor metus justo, ut fringilla enim fermentum sed.

Text

—

Ranges

0

Rects

0

Usage

Hook

import { useTextSelection } from "@usels/web";

function SelectionTracker() {
  const { text$, rects$, ranges$ } = useTextSelection();

  return (
    <div>
      <p>Select some text on the page</p>
      <p>Selected: {text$.get() || "Nothing selected"}</p>
      <p>Ranges: {ranges$.get().length}</p>
      <p>Rects: {rects$.get().length}</p>
    </div>
  );
}

Scope

import { createTextSelection } from "@usels/web";

function SelectionTracker() {
  "use scope"
  const { text$, rects$, ranges$ } = createTextSelection();

  return (
    <div>
      <p>Select some text on the page</p>
      <p>Selected: {text$.get() || "Nothing selected"}</p>
      <p>Ranges: {ranges$.get().length}</p>
      <p>Rects: {rects$.get().length}</p>
    </div>
  );
}

Highlight selected area

// @noErrors
import { useTextSelection } from "@usels/web";

function SelectionHighlight() {
  const { text$, rects$ } = useTextSelection();

  return (
    <>
      <p>Select any text to see highlight overlays</p>
      {rects$.get().map((rect, i) => (
        <div
          key={i}
          style={{
            position: "fixed",
            left: rect.x,
            top: rect.y,
            width: rect.width,
            height: rect.height,
            background: "rgba(59, 130, 246, 0.2)",
            pointerEvents: "none",
          }}
        />
      ))}
    </>
  );
}

Throttle during drag-select

During drag-selection, selectionchange fires many times per frame. Use throttle to limit how often the handler runs while the user is actively selecting.

const { text$ } = useTextSelection({ throttle: 100 }); // at most once per 100ms

Debounce for final selection only

Use debounce when you only care about the selection after the user has finished selecting, not the intermediate states.

const { text$ } = useTextSelection({ debounce: 200 }); // fires 200ms after selection stops

Type

Parameters

Parameter	Type	Description
options	UseTextSelectionOptions (optional)	-

UseTextSelectionOptions

Option	Type	Default	Description
throttle	MaybeObservable<number>	-	Throttle selectionchange handler in ms. Mutually exclusive with debounce.
debounce	MaybeObservable<number>	-	Debounce selectionchange handler in ms. Mutually exclusive with throttle.
window	WindowSource	-	-

Returns

UseTextSelectionReturn

Name	Type	Description
text$	ReadonlyObservable<string>	Selected text content
rects$	ReadonlyObservable<DOMRect[]>	Bounding rectangles of selected ranges
ranges$	ReadonlyObservable<Range[]>	Selection ranges
selection$	ReadonlyObservable<OpaqueObject<Selection> | null>	Current Selection object

Source

View on GitHub