TextSelection

Reactive tracking of text selection using the Selection API. Track what text the user has selected.

Loading demo...

Usage

import { Component } from '@angular/core';
import { textSelection } from '@signality/core';

@Component({
  template: `
    <p>Select some text in this paragraph to see it reflected below.</p>
    <p>Selected: "{{ selection.text() }}"</p>
  `,
})
export class SelectionDemo {
  readonly selection = textSelection(); 
}

Use InjectionToken for Singleton

For global state tracking like textSelection, consider using the provided TEXT_SELECTION token instead of calling the function directly. This provides a singleton instance that can be shared across your entire application, reducing memory usage and event listener overhead:

import { inject } from '@angular/core';
import { TEXT_SELECTION } from '@signality/core';

const selection = textSelection(); 
const selection = inject(TEXT_SELECTION); 

Learn more about Token-based utilities.

Parameters

Parameter	Type	Description
options	TextSelectionOptions	Optional configuration (see Options below)

Options

The TextSelectionOptions extends WithInjector:

Option	Type	Description
root	MaybeElementSignal<Element>	Optional element to track selection within. When provided, only selections entirely contained within this element are tracked.
injector	Injector	Optional injector for DI context

Return Value

The textSelection() function returns a TextSelectionRef object:

Property	Type	Description
text	Signal<string>	The selected text content
ranges	Signal<Range[]>	Array of Range objects
rects	Signal<DOMRect[]>	Bounding rectangles of selection (see DOMRect)
selection	Signal<Selection | null>	The raw Selection object
clear	() => void	Clear the current text selection

Examples

Quote selection

Use the root option to track selections only within a specific element:

import { Component, ElementRef, viewChild } from '@angular/core';
import { textSelection } from '@signality/core';

@Component({
  template: `
    <article #root>
      <p>Select text to save as a quote...</p>
    </article>
    @if (selection.text()) {
      <button (click)="saveQuote()">Save Quote</button>
    }
  `
})
export class QuoteCollector {
  readonly root = viewChild('root', { read: ElementRef });
  readonly selection = textSelection({ root: this.root }); 
  
  saveQuote() {
    const text = this.selection.text().trim();
    // ...
  }
}

SSR Compatibility

On the server, signals initialize with safe defaults:

• text() → ''
• ranges() → []
• rects() → []
• selection() → null
• clear() → no-op function

Type Definitions

interface TextSelectionOptions extends WithInjector {
  readonly root?: MaybeElementSignal<Element>;
}

interface TextSelectionRef {
  readonly text: Signal<string>;
  readonly ranges: Signal<Range[]>;
  readonly rects: Signal<DOMRect[]>;
  readonly selection: Signal<Selection | null>;
  readonly clear: () => void;
}

function textSelection(options?: TextSelectionOptions): TextSelectionRef;

const TEXT_SELECTION: InjectionToken<TextSelectionRef>;

Edit this page on GitHub Last updated: Apr 27, 2026, 21:07:43

PreviousTextDirectionNextVibration