Class

TooltipManager (ui)

@ckeditor/ckeditor5-ui/src/tooltipmanager

class

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

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

  • readonly

    tooltipTextView : object

    The view rendering text of the tooltip.

  • private

    _currentElementWithTooltip : null | HTMLElement

    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

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

  • private

    _mutationObserver : null | MutationObserverWrapper

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

  • private

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

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

  • private

    _resizeObserver : null | ResizeObserver

    An instance of the resize observer that keeps track on target element visibility, when it hides the tooltip should also disappear.

    configuration.

  • private readonly

    _watchdogExcluded : true

Static properties

  • static

    defaultBalloonPositions : Record<string, PositioningFunction>

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

  • private static

    _editors : Set<Editor>

    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

    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 )

    Creates an instance of the tooltip manager.

    Parameters

    editor : Editor
  • inherited

    delegate( events ) → EmitterMixinDelegateChain

    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

    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' ]

    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

    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

    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 : Node | Window

    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

    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

    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

    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

    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

    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 ] : Emitter | Node | Window

    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

    Handles displaying tooltips on mouseenter and focus in DOM.

    Parameters

    evt : unknown

    An object containing information about the fired event.

    domEvent : any

    The DOM event.

    Returns

    void
  • private

    _onLeaveOrBlur( evt, domEvent ) → void

    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

    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

    Pins the tooltip to a specific DOM element.

    Parameters

    targetDomElement : HTMLElement
    __namedParameters : TooltipData

    Returns

    void
  • private

    _unpinTooltip() → void

    Unpins the tooltip and cancels all queued pinning.

    Returns

    void
  • private

    _updateTooltipPosition() → void

    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