CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

TooltipManager (ui)

@ckeditor/ckeditor5-ui/src/tooltipmanager

class
See source

A tooltip manager class for the UI of the editor.

Note: Most likely you do not have to use the TooltipManager API listed below in order to display tooltips. Popular UI components support tooltips out-of-the-box via observable properties (see tooltip and tooltipPosition).

Displaying tooltips

To display a tooltip, set data-cke-tooltip-text attribute on any DOM element:

domElement.dataset.ckeTooltipText = 'My tooltip';

The tooltip will show up whenever the user moves the mouse over the element or the element gets focus in DOM.

Positioning tooltips

To change the position of the tooltip, use the data-cke-tooltip-position attribute (s, se, sw, n, e, or w):

domElement.dataset.ckeTooltipText = 'Tooltip to the north';
domElement.dataset.ckeTooltipPosition = 'n';

Disabling tooltips

In order to disable the tooltip temporarily, use the data-cke-tooltip-disabled attribute:

domElement.dataset.ckeTooltipText = 'Disabled. For now.';
domElement.dataset.ckeTooltipDisabled = 'true';

Styling tooltips

By default, the tooltip has .ck-tooltip class and its text inner .ck-tooltip__text.

If your tooltip requires custom styling, using data-cke-tooltip-class attribute will add additional class to the balloon displaying the tooltip:

domElement.dataset.ckeTooltipText = 'Tooltip with a red text';
domElement.dataset.ckeTooltipClass = 'my-class';

.ck.ck-tooltip.my-class { color: red }

Note: This class is a singleton. All editor instances re-use the same instance loaded by EditorUI of the first editor.

Filtering

Properties

  • readonly

    balloonPanelView : BalloonPanelView

    See source

    The instance of the balloon panel that renders and positions the tooltip.

  • readonly

    tooltipTextView : object

    See source

    The view rendering text of the tooltip.

  • private

    _currentElementWithTooltip : null | HTMLElement

    See source

    Stores the reference to the DOM element the tooltip is attached to. null when there's no tooltip in the UI.

  • private

    _currentTooltipPosition : null | TooltipPosition

    See source

    Stores the current tooltip position. null when there's no tooltip in the UI.

  • private

    _mutationObserver : null | MutationObserverWrapper

    See source

    An instance of the mutation observer that keeps track on target element attributes changes.

  • private

    _pinTooltipDebounced : DebouncedFunc<( HTMLElement, TooltipData ) => void>

    See source

    A debounced version of _pinTooltip. Tooltips show with a delay to avoid flashing and to improve the UX.

  • private

    _unpinTooltipDebounced : DebouncedFunc<VoidFunction>

    See source

    A debounced version of _unpinTooltip. Tooltips hide with a delay to allow hovering of their titles.

  • private readonly

    _watchdogExcluded : true

    See source

Static properties

  • static

    defaultBalloonPositions : Record<string, PositioningFunction>

    See source

    A set of default positioning functions used by the TooltipManager to pin tooltips in different positions.

  • private static

    _editors : Set<Editor>

    See source

    A set of editors the single tooltip manager instance must listen to. This is mostly to handle EditorUI#update listeners from individual editors.

  • private static

    _instance : null | TooltipManager

    See source

    A reference to the TooltipManager instance. The class is a singleton and as such, successive attempts at creating instances should return this instance.

Methods

  • constructor( editor )

    See source

    Creates an instance of the tooltip manager.

    Parameters

    editor : Editor

  • inherited

    delegate( events ) → EmitterMixinDelegateChain

    See source

    Delegates selected events to another Emitter. For instance:

    emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );

    then eventX is delegated (fired by) emitterB and emitterC along with data:

    emitterA.fire( 'eventX', data );

    and eventY is delegated (fired by) emitterC along with data:

    emitterA.fire( 'eventY', data );

    Parameters

    events : Array<string>

    Event names that will be delegated to another emitter.

    Returns

    EmitterMixinDelegateChain

  • destroy( editor ) → void

    See source

    Destroys the tooltip manager.

    Note: The manager singleton cannot be destroyed until all editors that use it are destroyed.

    Parameters

    editor : Editor

    The editor the manager was created for.

    Returns

    void

  • inherited

    fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]

    See source

    Fires an event, executing all callbacks registered for it.

    The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    eventOrInfo : GetNameOrEventInfo<TEvent>

    The name of the event or EventInfo object if event is delegated.

    args : TEvent[ 'args' ]

    Additional arguments to be passed to the callbacks.

    Returns

    GetEventInfo<TEvent>[ 'return' ]

    By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).

  • inherited

    listenTo( emitter, event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired in a specific (emitter) object.

    Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.

    // myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );

    An event callback can stop the event and set the return value of the fire method.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    emitter : Emitter

    The object that fires the event.

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : CallbackOptions

    Additional options.

    Returns

    void

  • inherited

    listenTo( emitter, event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired in a specific Emitter or DOM Node. It is backwards compatible with listenTo.

    Type parameters

    K : extends keyof DomEventMap

    Parameters

    emitter : Window | Node

    The object that fires the event.

    event : K

    The name of the event.

    callback : ( TooltipManager, EventInfo<string, unknown>, DomEventMap[ K ] ) => void

    The function to be called on event.

    [ options ] : object

    Additional options.

    Returns

    void

  • inherited

    off( event, callback ) → void

    See source

    Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).

    Parameters

    event : string

    The name of the event.

    callback : Function

    The function to stop being called.

    Returns

    void

  • inherited

    on( event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired.

    Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    once( event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    stopDelegating( [ event ], [ emitter ] ) → void

    See source

    Stops delegating events. It can be used at different levels:

    • To stop delegating all events.
    • To stop delegating a specific event to all emitters.
    • To stop delegating a specific event to a specific emitter.

    Parameters

    [ event ] : string

    The name of the event to stop delegating. If omitted, stops it all delegations.

    [ emitter ] : Emitter

    (requires event) The object to stop delegating a particular event to. If omitted, stops delegation of event to all emitters.

    Returns

    void

  • inherited

    stopListening( [ emitter ], [ event ], [ callback ] ) → void

    See source

    Stops listening for events. It can be used at different levels: It is backwards compatible with listenTo.

    • To stop listening to a specific callback.
    • To stop listening to a specific event.
    • To stop listening to all events fired by a specific object.
    • To stop listening to all events fired by all objects.

    Parameters

    [ emitter ] : Window | Node | Emitter

    The object to stop listening to. If omitted, stops it for all objects.

    [ event ] : string

    (Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.

    [ callback ] : Function

    (Requires the event) The function to be removed from the call list for the given event.

    Returns

    void

  • private

    _onEnterOrFocus( evt, domEvent ) → void

    See source

    Handles displaying tooltips on mouseenter and focus in DOM.

    Parameters

    evt : EventInfo<string, unknown>

    An object containing information about the fired event.

    domEvent : any

    The DOM event.

    Returns

    void

  • private

    _onKeyDown( evt, domEvent ) → void

    See source

    Handles hiding tooltips on keydown in DOM.

    Parameters

    evt : EventInfo<string, unknown>

    An object containing information about the fired event.

    domEvent : KeyboardEvent

    The DOM event.

    Returns

    void

  • private

    _onLeaveOrBlur( evt, domEvent ) → void

    See source

    Handles hiding tooltips on mouseleave and blur in DOM.

    Parameters

    evt : EventInfo<string, unknown>

    An object containing information about the fired event.

    domEvent : any

    The DOM event.

    Returns

    void

  • private

    _onScroll( evt, domEvent ) → void

    See source

    Handles hiding tooltips on scroll in DOM.

    Parameters

    evt : unknown

    An object containing information about the fired event.

    domEvent : any

    The DOM event.

    Returns

    void

  • private

    _pinTooltip( targetDomElement, __namedParameters ) → void

    See source

    Pins the tooltip to a specific DOM element.

    Parameters

    targetDomElement : HTMLElement
    __namedParameters : TooltipData

    Returns

    void

  • private

    _unpinTooltip() → void

    See source

    Unpins the tooltip and cancels all queued pinning.

    Returns

    void

  • private

    _updateTooltipPosition() → void

    See source

    Updates the position of the tooltip so it stays in sync with the element it is pinned to.

    Hides the tooltip when the element is no longer visible in DOM or the tooltip text was removed.

    Returns

    void

Static methods