CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 5/API
Class

Selection (engine/view)

@ckeditor/ckeditor5-engine/src/view/selection

class

Class representing selection in tree view.

Selection can consist of ranges that can be set using setTo method. That method create copies of provided ranges and store those copies internally. Further modifications to passed ranges will not change selection's state. Selection's ranges can be obtained via getRanges, getFirstRange and getLastRange methods, which return copies of ranges stored inside selection. Modifications made on these copies will not change selection's state. Similar situation occurs when getting anchor, focus, first and last positions - all will return copies of requested positions.

Filtering

Properties

  • anchor : Position

    Selection anchor. Anchor may be described as a position where the selection starts. Together with focus they define the direction of selection, which is important when expanding/shrinking selection. Anchor is always the start or end of the most recent added range. It may be a bit unintuitive when there are multiple ranges in selection.

  • editableElement : EditableElement | null

    EditableElement instance that contains this selection, or null if the selection is not inside an editable element.

  • fakeSelectionLabel

    Returns fake selection label.

  • focus : Position

    Selection focus. Focus is a position where the selection ends.

  • isBackward : Boolean

    Specifies whether the focus precedes anchor.

  • isCollapsed : Boolean

    Returns whether the selection is collapsed. Selection is collapsed when there is exactly one range which is collapsed.

  • isFake

    Returns true if selection instance is marked as fake.

  • rangeCount : Number

    Returns number of ranges in selection.

  • _lastRangeBackward : Boolean

    protected

    Specifies whether the last added range was added as a backward or forward range.

  • _ranges : Array.<Range>

    protected

    Stores all ranges that are selected.

  • _fakeSelectionLabel : String

    private

    Fake selection's label.

  • _isFake : Boolean

    private

    Specifies whether selection instance is fake.

Methods

  • constructor( [ selectable ], [ placeOrOffset ], [ options ] = { [options.backward], [options.fake], [options.label] } )

    Creates new selection instance. 

    // Creates empty selection without ranges.
const selection = new Selection();

// Creates selection at the given range.
const range = new Range( start, end );
const selection = new Selection( range );

// Creates selection at the given ranges
const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
const selection = new Selection( ranges );

// Creates selection from the other selection.
const otherSelection = new Selection();
const selection = new Selection( otherSelection );

// Creates selection from the document selection.
const selection = new Selection( editor.editing.view.document.selection );

// Creates selection at the given position.
const position = new Position( root, path );
const selection = new Selection( position );

// Creates collapsed selection at the position of given item and offset.
const paragraph = writer.createContainerElement( 'paragraph' );
const selection = new Selection( paragraph, offset );

// Creates a range inside an element which starts before the
// first child of that element and ends after the last child of that element.
const selection = new Selection( paragraph, 'in' );

// Creates a range on an item which starts before the item and ends
// just after the item.
const selection = new Selection( paragraph, 'on' );

    Selection's constructor allow passing additional options (backward, fake and label) as the last argument.

    // Creates backward selection.
const selection = new Selection( range, { backward: true } );

    Fake selection does not render as browser native selection over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to the user and selection over elements can be represented in other way, for example by applying proper CSS class.

    Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM (and be properly handled by screen readers).

    // Creates fake selection with label.
const selection = new Selection( range, { fake: true, label: 'foo' } );

    Parameters

    [ selectable ] : Selection | DocumentSelection | Position | Iterable.<Range> | Range | Item | null
    [ placeOrOffset ] : Number | 'before' | 'end' | 'after' | 'on' | 'in'

    Offset or place when selectable is an Item.

    [ options ] : Object
    Properties
    [ options.backward ] : Boolean

    Sets this selection instance to be backward.

    [ options.fake ] : Boolean

    Sets this selection instance to be marked as fake.

    [ options.label ] : String

    Label for the fake selection.

  • getFirstPosition() → Position | null

    Returns copy of the first position in the selection. First position is the position that is before any other position in the selection ranges. Returns null if no ranges are added to selection.

    Returns

    Position | null

  • getFirstRange() → Range | null

    Returns copy of the first range in the selection. First range is the one which start position is before start position of all other ranges (not to confuse with the first range added to the selection). Returns null if no ranges are added to selection.

    Returns

    Range | null

  • getLastPosition() → Position | null

    Returns copy of the last position in the selection. Last position is the position that is after any other position in the selection ranges. Returns null if no ranges are added to selection.

    Returns

    Position | null

  • getLastRange() → Range | null

    Returns copy of the last range in the selection. Last range is the one which end position is after end position of all other ranges (not to confuse with the last range added to the selection). Returns null if no ranges are added to selection.

    Returns

    Range | null

  • getRanges() → Iterable.<Range>

    Returns an iterable that contains copies of all ranges added to the selection.

    Returns

    Iterable.<Range>

  • getSelectedElement() → Element | null

    Returns the selected element. Element is considered as selected if there is only one range in the selection, and that range contains exactly one element. Returns null if there is no selected element.

    Returns

    Element | null

  • isEqual( otherSelection ) → Boolean

    Checks whether, this selection is equal to given selection. Selections are equal if they have same directions, same number of ranges and all ranges from one selection equal to a range from other selection.

    Parameters

    otherSelection : Selection | DocumentSelection

    Selection to compare with.

    Returns

    Boolean

    true if selections are equal, false otherwise.

  • isSimilar( otherSelection ) → Boolean

    Checks whether this selection is similar to given selection. Selections are similar if they have same directions, same number of ranges, and all trimmed ranges from one selection are equal to any trimmed range from other selection.

    Parameters

    otherSelection : Selection | DocumentSelection

    Selection to compare with.

    Returns

    Boolean

    true if selections are similar, false otherwise.

  • setFocus( itemOrPosition, [ offset ] )

    Moves focus to the specified location.

    The location can be specified in the same form as createAt parameters.

    Parameters

    itemOrPosition : Item | Position
    [ offset ] : Number | 'end' | 'before' | 'after'

    Offset or one of the flags. Used only when first parameter is a view item.

    Defaults to 0

    Fires

  • setTo( selectable, [ placeOrOffset ], [ options ] = { [options.backward], [options.fake], [options.label] } )

    Sets this selection's ranges and direction to the specified location based on the given document selection, selection, position, item, range, an iterable of ranges or null. 

    // Sets selection to the given range.
const range = new Range( start, end );
selection.setTo( range );

// Sets selection to given ranges.
const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
selection.setTo( range );

// Sets selection to the other selection.
const otherSelection = new Selection();
selection.setTo( otherSelection );

 // Sets selection to contents of DocumentSelection.
selection.setTo( editor.editing.view.document.selection );

// Sets collapsed selection at the given position.
const position = new Position( root, path );
selection.setTo( position );

// Sets collapsed selection at the position of given item and offset.
selection.setTo( paragraph, offset );

    Creates a range inside an element which starts before the first child of that element and ends after the last child of that element.

    selection.setTo( paragraph, 'in' );

    Creates a range on an item which starts before the item and ends just after the item.

    selection.setTo( paragraph, 'on' );

// Clears selection. Removes all ranges.
selection.setTo( null );

    Selection#setTo() method allow passing additional options (backward, fake and label) as the last argument.

    // Sets selection as backward.
selection.setTo( range, { backward: true } );

    Fake selection does not render as browser native selection over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to the user and selection over elements can be represented in other way, for example by applying proper CSS class.

    Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM (and be properly handled by screen readers).

    // Creates fake selection with label.
selection.setTo( range, { fake: true, label: 'foo' } );

    Parameters

    selectable : Selection | DocumentSelection | Position | Iterable.<Range> | Range | Item | null
    [ placeOrOffset ] : Number | 'before' | 'end' | 'after' | 'on' | 'in'

    Sets place or offset of the selection.

    [ options ] : Object
    Properties
    [ options.backward ] : Boolean

    Sets this selection instance to be backward.

    [ options.fake ] : Boolean

    Sets this selection instance to be marked as fake.

    [ options.label ] : String

    Label for the fake selection.

    Fires

  • _addRange( range, [ isBackward ] )

    private

    Adds a range to the selection. Added range is copied. This means that passed range is not saved in the selection instance and you can safely operate on it.

    Accepts a flag describing in which way the selection is made - passed range might be selected from start to end or from end to start. The flag is used to set anchor and focus properties.

    Throws CKEditorError view-selection-range-intersects if added range intersects with ranges already stored in Selection instance.

    Parameters

    range : Range
    [ isBackward ] : Boolean

    Defaults to false

    Fires

  • _pushRange( range )

    private

    Adds range to selection - creates copy of given range so it can be safely used and modified.

    Throws CKEditorError view-selection-range-intersects if added range intersects with ranges already stored in selection instance.

    Parameters

    range : Range

  • _setFakeOptions( [ options ] = { [options.fake], [options.label] } )

    private

    Sets this selection instance to be marked as fake. A fake selection does not render as browser native selection over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to the user and selection over elements can be represented in other way, for example by applying proper CSS class.

    Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM (and be properly handled by screen readers).

    Parameters

    [ options ] : Object

    Options.

    Properties
    [ options.fake ] : Boolean

    If set to true selection will be marked as fake.

    [ options.label ] : String

    Fake selection label.

    Defaults to ''

  • _setRanges( newRanges, [ isLastBackward ] )

    private

    Replaces all ranges that were added to the selection with given array of ranges. Last range of the array is treated like the last added range and is used to set anchor and focus. Accepts a flag describing in which way the selection is made.

    Parameters

    newRanges : Iterable.<Range>

    Iterable object of ranges to set.

    [ isLastBackward ] : Boolean

    Flag describing if last added range was selected forward - from start to end (false) or backward - from end to start (true). Defaults to false.

    Defaults to false

Events

  • change( eventInfo )

    Fired whenever selection ranges are changed through Selection API.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.