CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

FocusCycler (ui)

@ckeditor/ckeditor5-ui/src/focuscycler

class
See source

A utility class that helps cycling over focusable views in a ViewCollection when the focus is tracked by the FocusTracker instance. It helps implementing keyboard navigation in HTML forms, toolbars, lists and the like.

To work properly it requires:

  • a collection of focusable (HTML tabindex attribute) views that implement the focus() method,
  • an associated focus tracker to determine which view is focused.

A simple cycler setup can look like this:

const focusables = new ViewCollection();
const focusTracker = new FocusTracker();

// Add focusable views to the focus tracker.
focusTracker.add( ... );

Then, the cycler can be used manually:

const cycler = new FocusCycler( { focusables, focusTracker } );

// Will focus the first focusable view in #focusables.
cycler.focusFirst();

// Will log the next focusable item in #focusables.
console.log( cycler.next );

Alternatively, it can work side by side with the KeystrokeHandler:

const keystrokeHandler = new KeystrokeHandler();

// Activate the keystroke handler.
keystrokeHandler.listenTo( sourceOfEvents );

const cycler = new FocusCycler( {
	focusables, focusTracker, keystrokeHandler,
	actions: {
		// When arrowup of arrowleft is detected by the #keystrokeHandler,
		// focusPrevious() will be called on the cycler.
		focusPrevious: [ 'arrowup', 'arrowleft' ],
	}
} );

Check out the "Deep dive into focus tracking" guide to learn more.

Filtering

Properties

  • readonly

    actions : Object

    See source

    Actions that the cycler can take when a keystroke is pressed. Requires options.keystrokeHandler to be passed and working. When an action is performed, preventDefault and stopPropagation will be called on the event the keystroke fired in the DOM.

    actions: {
	// Will call #focusPrevious() when arrowleft or arrowup is pressed.
	focusPrevious: [ 'arrowleft', 'arrowup' ],

	// Will call #focusNext() when arrowdown is pressed.
	focusNext: 'arrowdown'
}

  • readonly

    current : Number | null

    See source

    An index of the view in the focusables which is focused according to focusTracker. Returns null when there is no such view.

  • readonly

    first : View | null

    See source

    Returns the first focusable view in focusables. Returns null if there is none.

    Note: Hidden views (e.g. with display: none) are ignored.

  • readonly

    focusTracker : FocusTracker

    See source

    A focus tracker instance that the cycler uses to determine the current focus state in focusables.

  • readonly

    focusables : Collection

    See source

    A view collection that the cycler operates on.

  • readonly

    keystrokeHandler : KeystrokeHandler

    See source

    An instance of the KeystrokeHandler which can respond to certain keystrokes and cycle the focus.

  • readonly

    last : View | null

    See source

    Returns the last focusable view in focusables. Returns null if there is none.

    Note: Hidden views (e.g. with display: none) are ignored.

  • readonly

    next : View | null

    See source

    Returns the next focusable view in focusables based on current. Returns null if there is none.

    Note: Hidden views (e.g. with display: none) are ignored.

  • readonly

    previous : View | null

    See source

    Returns the previous focusable view in focusables based on current. Returns null if there is none.

    Note: Hidden views (e.g. with display: none) are ignored.

Methods

  • constructor( options = { options.focusables, options.focusTracker, [options.keystrokeHandler], [options.actions] } )

    See source

    Creates an instance of the focus cycler utility.

    Parameters

    options : Object

    Configuration options.

    Properties
    options.focusables : Collection | Object
    options.focusTracker : FocusTracker
    [ options.keystrokeHandler ] : KeystrokeHandler
    [ options.actions ] : Object

  • focusFirst()

    See source

    Focuses the first item in focusables.

    Note: Hidden views (e.g. with display: none) are ignored.

  • focusLast()

    See source

    Focuses the last item in focusables.

    Note: Hidden views (e.g. with display: none) are ignored.

  • focusNext()

    See source

    Focuses the next item in focusables.

    Note: Hidden views (e.g. with display: none) are ignored.

  • focusPrevious()

    See source

    Focuses the previous item in focusables.

    Note: Hidden views (e.g. with display: none) are ignored.

  • protected

    _focus( view )

    See source

    Focuses the given view if it exists.

    Parameters

    view : View

  • protected

    _getFocusableItem( step ) → View | null

    See source

    Returns the next or previous focusable view in focusables with respect to current.

    Parameters

    step : Number

    Either 1 for checking forward from current or -1 for checking backwards.

    Returns

    View | null