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

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

    See source
    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.

    See source

  • first : View | null

    readonly

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

    See source

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

  • focusTracker : FocusTracker

    readonly

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

    See source

  • focusables : Collection

    readonly

    A view collection that the cycler operates on.

    See source

  • keystrokeHandler : KeystrokeHandler

    readonly

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

    See source

  • last : View | null

    readonly

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

    See source

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

  • next : View | null

    readonly

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

    See source

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

  • previous : View | null

    readonly

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

    See source

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

Methods

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

    Creates an instance of the focus cycler utility.

    See source

    Parameters

    options : Object

    Configuration options.

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

  • focusFirst()

    Focuses the first item in focusables.

    See source

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

  • focusLast()

    Focuses the last item in focusables.

    See source

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

  • focusNext()

    Focuses the next item in focusables.

    See source

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

  • focusPrevious()

    Focuses the previous item in focusables.

    See source

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

  • _focus( view )

    protected

    Focuses the given view if it exists.

    See source

    Parameters

    view : View

  • _getFocusableItem( step ) → View | null

    protected

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

    See source

    Parameters

    step : Number

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

    Returns

    View | null