CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

Selection (engine/view)

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

class
See source

Class representing an arbirtary selection in the view. See also DocumentSelection.

New selection instances can be created via the constructor or one these methods:

A selection can consist of ranges that can be set by using the Selection#setTo() method.

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.

    See source

    Related:

  • editableElement : EditableElement | null

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

    See source

  • fakeSelectionLabel : String

    Returns fake selection label.

    See source

    Related:

  • focus : Position

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

    See source

    Related:

  • isBackward : Boolean

    Specifies whether the focus precedes anchor.

    See source

  • isCollapsed : Boolean

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

    See source

  • isFake : Boolean

    Returns true if selection instance is marked as fake.

    See source

    Related:

  • rangeCount : Number

    Returns number of ranges in selection.

    See source

  • _lastRangeBackward : Boolean

    protected

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

    See source

  • _ranges : Array.<Range>

    protected

    Stores all ranges that are selected.

    See source

  • _fakeSelectionLabel : String

    private

    Fake selection's label.

    See source

  • _isFake : Boolean

    private

    Specifies whether selection instance is fake.

    See source

Methods

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

    Creates new selection instance.

    See source

    Note: The selection constructor is available as a factory method:

    • View#createSelection(),

    • UpcastWriter#createSelection().

      // Creates empty selection without ranges.
const selection = writer.createSelection();

// Creates selection at the given range.
const range = writer.createRange( start, end );
const selection = writer.createSelection( range );

// Creates selection at the given ranges
const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
const selection = writer.createSelection( ranges );

// Creates selection from the other selection.
const otherSelection = writer.createSelection();
const selection = writer.createSelection( otherSelection );

// Creates selection from the document selection.
const selection = writer.createSelection( editor.editing.view.document.selection );

// Creates selection at the given position.
const position = writer.createPositionFromPath( root, path );
const selection = writer.createSelection( position );

// Creates collapsed selection at the position of given item and offset.
const paragraph = writer.createContainerElement( 'paragraph' );
const selection = writer.createSelection( 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 = writer.createSelection( paragraph, 'in' );

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

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

    // Creates backward selection.
const selection = writer.createSelection( 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 = writer.createSelection( range, { fake: true, label: 'foo' } );

    Parameters

    [ selectable ] : Selectable
    [ 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.

    See source

    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.

    See source

    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.

    See source

    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.

    See source

    Returns

    Range | null

  • getRanges() → Iterable.<Range>

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

    See source

    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.

    See source

    Returns

    Element | null

  • is( type ) → Boolean

    Checks whether this object is of the given type.

    See source
    selection.is( 'selection' ); // -> true
selection.is( 'view:selection' ); // -> true

selection.is( 'model:selection' ); // -> false
selection.is( 'element' ); // -> false
selection.is( 'range' ); // -> false

    Check the entire list of view objects which implement the is() method.

    Parameters

    type : String

    Returns

    Boolean

  • 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.

    See source

    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.

    See source

    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.

    See source

    The location can be specified in the same form as view.createPositionAt() 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.

    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 selectable.

    See source
    	// Sets selection to the given range.
	const range = writer.createRange( start, end );
	selection.setTo( range );

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

	// Sets selection to the other selection.
	const otherSelection = writer.createSelection();
	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 = writer.createPositionAt( 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 : Selectable
    [ 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.

    See source

    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.

    See source

    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.

    See source

    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.

    See source

    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.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.