# OverlayHost

class

Keeps a feature's floating UI – its balloons, dialogs, panels and the tooltips inside them – in the right DOM tree, and keeps it there as the feature moves.

For a feature that renders its UI _outside_ an editor, in a container the integrator may put anywhere, including inside a shadow root. An editor's own floating UI needs none of this: it is mounted in the root the editor lives in and stays there.

#### Why it is needed

Floating UI is mounted through a [`BodyCollection`](module_ui_editorui_bodycollection-BodyCollection.md), and it has to go into the same tree as the feature it belongs to. Anywhere else it loses the styles scoped to that tree, and its tooltips come out clipped or mis-styled across the shadow boundary.

Doing that by hand means re-mounting the collection whenever the container moves, unmounting it while the container is detached, registering and unregistering it with the shared [`TooltipManager`](module_ui_tooltipmanager-TooltipManager.md), tracking the shadow roots of the inline UI so that tooltips and click-outside detection reach across boundaries, and tearing it all down in the right order. This class does all of it, behind resolvers that say where the feature's UI currently is.

#### How to use it

```typescript
const host = new OverlayHost( locale, {
	resolveMountTarget: () => getOverlayMountRoot( featureContainer ),
	resolveInlineContainer: () => featureContainer
} );

host.sync();
host.bodyCollection.add( balloonPanelView );
```

Add the feature's floating views to [`bodyCollection`](#member-bodyCollection). Call [`sync`](#function-sync) whenever the container may have moved – right before showing a panel, for instance – and [`destroy`](#function-destroy) once the feature goes away. It re-syncs on its own too: whenever a view is added to the collection, and on every `update` event of an [`updateEmitter`](module_ui_overlayhost-OverlayHostOptions.md#member-updateEmitter), if one is given.

An editor's [`EditorUI`](module_ui_editorui_editorui-EditorUI.md) uses this class as well, lending it the body collection and shadow root registry it already has.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L65)

<a id="properties">

## Properties

<a id="member-bodyCollection">

### `bodyCollection: BodyCollection` _(readonly)_

The body collection holding the floating views. Add the feature's balloons and panels here.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L69)

<a id="member-shadowRootRegistry">

### `shadowRootRegistry: ShadowRootRegistry` _(readonly)_

Tracks the shadow roots hosting the tooltip-bearing UI that lives outside the [`bodyCollection`](#member-bodyCollection): the [inline UI container](module_ui_overlayhost-OverlayHostOptions.md#member-resolveInlineContainer) and any nodes registered directly by the owner (an editor registers its editables, toolbars and menu bar).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L76)

<a id="member-_destroyed">

### `_destroyed: boolean` _(private)_

Whether [`destroy`](#function-destroy) has run, so a repeated call does not release the shared tooltip manager on behalf of another holder.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L122)

<a id="member-_ownsBodyCollection">

### `_ownsBodyCollection: boolean` _(private)_

Whether the [`bodyCollection`](#member-bodyCollection) was created by this host (and is destroyed with it), as opposed to a borrowed one whose owner manages its life cycle.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L103)

<a id="member-_ownsShadowRootRegistry">

### `_ownsShadowRootRegistry: boolean` _(private)_

Whether the [`shadowRootRegistry`](#member-shadowRootRegistry) was created by this host (and is destroyed with it), as opposed to a borrowed one whose owner manages its life cycle.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L109)

<a id="member-_ownsTooltipManagerReference">

### `_ownsTooltipManagerReference: boolean` _(private)_

Whether this host acquired its own reference to the shared tooltip manager (and releases it on [`destroy`](#function-destroy)), as opposed to using a borrowed reference whose holder releases it – an editor counts as a single holder no matter how it splits the work internally.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L116)

<a id="member-_registeredInlineContainer">

### `_registeredInlineContainer: ShadowRoot | HTMLElement | null` _(private)_

The inline UI container currently registered with [`shadowRootRegistry`](#member-shadowRootRegistry), so it can be replaced when the feature moves to a different container.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L97)

<a id="member-_resolveInlineContainer">

### `_resolveInlineContainer?: () => ( ShadowRoot | HTMLElement | null | undefined )` _(private)_

See [`resolveInlineContainer`](module_ui_overlayhost-OverlayHostOptions.md#member-resolveInlineContainer).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L91)

<a id="member-_resolveMountTarget">

### `_resolveMountTarget: () => ( ShadowRoot | HTMLElement | null )` _(private)_

See [`resolveMountTarget`](module_ui_overlayhost-OverlayHostOptions.md#member-resolveMountTarget).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L86)

<a id="member-_tooltipManager">

### `_tooltipManager: TooltipManager` _(private)_

The shared tooltip manager the [`bodyCollection`](#member-bodyCollection) is registered with.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L81)

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( locale, options )`

Creates the host: the [`bodyCollection`](#member-bodyCollection) (unless a borrowed one is given) and its registration in the shared [`TooltipManager`](module_ui_tooltipmanager-TooltipManager.md). The collection is not mounted in the DOM yet – call [`sync`](#function-sync) for that.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L132)

#### Parameters

* `locale: Locale`

  The locale of the feature (used by the body collection and the tooltip views).

* `options: OverlayHostOptions`

  The resolvers describing where the feature UI lives.

<a id="function-delegate">

### `delegate( events ) → EmitterMixinDelegateChain` _(inherited)_

Delegates selected events to another [`Emitter`](module_utils_emittermixin-Emitter.md). For instance:

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

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

```typescript
emitterA.fire( 'eventX', data );
```

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

```typescript
emitterA.fire( 'eventY', data );
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L539)

#### Parameters

* `events: Array<string>`

  Event names that will be delegated to another emitter.

#### Returns

* `EmitterMixinDelegateChain`

<a id="function-destroy">

### `destroy() → void`

Destroys the host: stops hosting tooltips in the [`bodyCollection`](#member-bodyCollection), releases the shared [`TooltipManager`](module_ui_tooltipmanager-TooltipManager.md) (so it is destroyed with its last holder) and destroys the collection together with its views and the [`shadowRootRegistry`](#member-shadowRootRegistry) – except the borrowed ones, which their owners destroy. Safe to call more than once.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L202)

#### Returns

* `void`

<a id="function-fire">

### `fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]` _(inherited)_

Fires an event, executing all callbacks registered for it.

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L512)

#### Type parameters

* `TEvent: extends BaseEvent`

  The type describing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### 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`](module_utils_eventinfo-EventInfo.md#member-return)'s property (the event info is the first param of every callback).

<a id="function-listenTo:BASE_EMITTER">

### `listenTo( emitter, event, callback, options? ) → void` _(inherited)_

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.

```typescript
// 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](module_utils_eventinfo-EventInfo.md#member-stop) and set the [return value](module_utils_eventinfo-EventInfo.md#member-return) of the [`fire`](#function-fire) method.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L475)

#### Type parameters

* `TEvent: extends BaseEvent`

  The type describing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### 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?: GetCallbackOptions<TEvent>`

  Additional options.

#### Returns

* `void`

<a id="function-off">

### `off( event, callback ) → void` _(inherited)_

Stops executing the callback on the given event. Shorthand for [`this.stopListening( this, event, callback )`](#function-stopListening:BASE_STOP).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L444)

#### Parameters

* `event: string`

  The name of the event.

* `callback: Function`

  The function to stop being called.

#### Returns

* `void`

<a id="function-on">

### `on( event, callback, options? ) → void` _(inherited)_

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

Shorthand for [`this.listenTo( this, event, callback, options )`](#function-listenTo:BASE_EMITTER) (it makes the emitter listen on itself).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L416)

#### Type parameters

* `TEvent: extends BaseEvent`

  The type descibing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### 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`

<a id="function-once">

### `once( event, callback, options? ) → void` _(inherited)_

Registers a callback function to be executed on the next time the event is fired only. This is similar to calling [`on`](#function-on) followed by [`off`](#function-off) in the callback.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L431)

#### Type parameters

* `TEvent: extends BaseEvent`

  The type descibing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### 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`

<a id="function-stopDelegating">

### `stopDelegating( event?, emitter? ) → void` _(inherited)_

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.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L552)

#### 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`

<a id="function-stopListening:BASE_STOP">

### `stopListening( emitter?, event?, callback? ) → void` _(inherited)_

Stops listening for events. It can be used at different levels:

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L497)

#### Parameters

* `emitter?: 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`

<a id="function-sync">

### `sync() → void`

Brings the host up to date with the resolved targets:

* keeps the [`bodyCollection`](#member-bodyCollection) mounted in the target resolved by [`resolveMountTarget`](module_ui_overlayhost-OverlayHostOptions.md#member-resolveMountTarget) (re-mounting only when the target changes, unmounting on `null`);
* keeps the [inline UI container](module_ui_overlayhost-OverlayHostOptions.md#member-resolveInlineContainer) tracked for tooltips, re-resolving its shadow root in case a detached container has become connected.

Idempotent – call it whenever the targets may have changed: after attaching the feature to a container, right before showing a floating panel (an editor's UI may be mounted lazily), or on any relevant layout change.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/overlayhost.ts#L174)

#### Returns

* `void`

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)