Class

FocusCycler (ui)

@ckeditor/ckeditor5-ui/src/focuscycler

class

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' ],
    }
} );

Filtering

Properties

  • actions : Object

    readonly

    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'
    }
  • current : Number | null

    readonly

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

  • first : View | null

    readonly

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

  • focusTracker : FocusTracker

    readonly

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

  • focusables : Collection

    readonly

    A view collection that the cycler operates on.

  • keystrokeHandler : KeystrokeHandler

    readonly

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

  • last : View | null

    readonly

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

  • next : View | null

    readonly

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

  • previous : View | null

    readonly

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

Methods