# BodyCollection

class

This is a special [`ViewCollection`](module_ui_viewcollection-ViewCollection.md) dedicated to elements that are detached from the DOM structure of the editor, like floating panels, floating toolbars, dialogs, etc.

The body collection is available under the [`editor.ui.view.body`](module_ui_editorui_editoruiview-EditorUIView.md#member-body) property. Any plugin can add a [view](module_ui_view-View.md) to this collection.

All views added to a body collection render in a dedicated DOM container (`<div class="ck ck-body ...">...</div>`). All body collection containers render in a common shared (`<div class="ck-body-wrapper">...</div>`) in the DOM to limit the pollution of the `<body>` element. The resulting DOM structure is as follows:

```html
<body>
	<!-- Content of the webpage... -->

	<!-- The shared wrapper for all body collection containers. -->
	<div class="ck-body-wrapper">
		<!-- The container of the first body collection instance. -->
		<div class="ck ck-body ...">
			<!-- View elements belonging to the first body collection -->
		</div>

		<!-- The container of the second body collection instance. -->
		<div class="ck ck-body ...">...</div>

		<!-- More body collection containers for the rest of instances... -->
	</div>
</body>
```

By default, the [`editor.ui.view`](module_ui_editorui_editoruiview-EditorUIView.md) manages the life cycle of the [`editor.ui.view.body`](module_ui_editorui_editoruiview-EditorUIView.md#member-body) collection, attaching and detaching it when the editor gets created or [destroyed](module_core_editor_editor-Editor.md#function-destroy).

#### Custom body collection instances

Even though most editor instances come with a built-in body collection ([`editor.ui.view.body`](module_ui_editorui_editoruiview-EditorUIView.md#member-body)), you can create your own instance of this class if you need to control their life cycle.

The life cycle of a custom body collection must be handled manually by the developer using the dedicated API:

* A body collection will render itself automatically in the DOM as soon as you call [`attachToDom`](#function-attachToDom).
* Calling [`destroy`](#function-destroy) will remove the collection from the DOM and destroy its views.

**Note**: The shared collection wrapper (`<div class="ck-body-wrapper">...</div>`) gets automatically removed from DOM when the last body collection is [destroyed](#function-destroy) and does not require any special handling.

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

<a id="properties">

## Properties

<a id="member-bodyCollectionContainer">

### `bodyCollectionContainer: HTMLElement` _(readonly)_

The element holding elements of the body collection. It is created on demand – the first time it is accessed or the collection is [attached](#function-attachToDom) – and reused afterwards. Creating it does not attach it to the DOM (that happens in [`attachToDom`](#function-attachToDom)), so it is available for focus tracking and styling even while the collection is not mounted yet.

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

<a id="member-first">

### `first: T | null` _(readonly)_

Returns the first item from the collection or null when collection is empty.

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

<a id="member-id">

### `id?: string` _(inherited)_

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

<a id="member-last">

### `last: T | null` _(readonly)_

Returns the last item from the collection or null when collection is empty.

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

<a id="member-length">

### `length: number` _(readonly)_

The number of items available in the collection.

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

<a id="member-locale">

### `locale: Locale` _(readonly)_

The [editor's locale](module_core_editor_editor-Editor.md#member-locale) instance. See the view [locale](module_ui_view-View.md#member-locale) property.

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

<a id="member-mountTarget">

### `mountTarget: ShadowRoot | HTMLElement | undefined` _(readonly)_

The mount target (element or shadow root) the collection is currently attached to, or `undefined` before [`attachToDom`](#function-attachToDom) is called or after [`unmountFromDom`](#function-unmountFromDom) or [`destroy`](#function-destroy).

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

<a id="member-_bodyCollectionContainer">

### `_bodyCollectionContainer?: HTMLElement` _(private)_

The element holding elements of the body collection.

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

<a id="member-_mountTarget">

### `_mountTarget?: ShadowRoot | HTMLElement` _(private)_

The mount target the [`_bodyCollectionContainer`](#member-_bodyCollectionContainer) is currently attached to (through the shared wrapper): the `document.body` for editors in the light DOM, or a `ShadowRoot` (or a configured element) for editors living inside a shadow root. Tracked so the collection can be re-mounted into a different target and cleaned up from the right wrapper.

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

#### Static properties

<a id="static-member-_bodyWrappers">

### `_bodyWrappers: Map<ShadowRoot | HTMLElement, HTMLElement>` _(private)_

The shared wrapper elements that hold the [`_bodyCollectionContainer`](#member-_bodyCollectionContainer) elements, keyed by the mount target (the element or shadow root the wrapper is attached to – not the editor's editing root). Body collections attached to the same target (e.g. the same shadow root) share a single wrapper; body collections attached to different targets get separate wrappers.

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

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( locale, initialItems )`

Creates a new instance of the [`BodyCollection`](module_ui_editorui_bodycollection-BodyCollection.md).

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

#### Parameters

* `locale: Locale`

  The [editor's locale](module_core_editor_editor-Editor.md) instance.

* `initialItems: Iterable<View<HTMLElement>>`

  The initial items of the collection.

  Defaults to `[]`

<a id="function-Symbol.iterator">

### `Symbol.iterator() → Iterator<View<HTMLElement>>` _(inherited)_

Iterable interface.

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

#### Returns

* `Iterator<View<HTMLElement>>`

<a id="function-add">

### `add( item, index? ) → this` _(inherited)_

Adds an item into the collection.

If the item does not have an id, then it will be automatically generated and set on the item.

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

#### Parameters

* `item: View`

* `index?: number`

  The position of the item in the collection. The item is pushed to the collection when `index` not specified.

#### Returns

* `this`

#### Fires

* [add](#event-add)
* [change](#event-change)

<a id="function-addMany">

### `addMany( items, index? ) → this` _(inherited)_

Adds multiple items into the collection.

Any item not containing an id will get an automatically generated one.

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

#### Parameters

* `items: Iterable<View<HTMLElement>>`

* `index?: number`

  The position of the insertion. Items will be appended if no `index` is specified.

#### Returns

* `this`

#### Fires

* [add](#event-add)
* [change](#event-change)

<a id="function-attachToDom">

### `attachToDom( target? ) → void`

Attaches the body collection to the DOM. You need to execute this method to render the content of the body collection.

By default the collection mounts in a shared wrapper under the `document.body`. Pass a `target` to mount it elsewhere – for example inside the [shadow root](module_utils_dom_isshadowroot.md#function-isShadowRoot) an editor lives in, so that floating UI (balloons, dialogs, tooltips) can be styled within that boundary. The `target` may be a regular element or a shadow root, open or closed. Calling this method again with a different `target` re-mounts the already rendered collection into the new location.

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

#### Parameters

* `target?: ShadowRoot | HTMLElement`

  The element or shadow root to mount the body collection in. Defaults to `document.body`.

#### Returns

* `void`

<a id="function-bindTo">

### `bindTo( externalCollection ) → CollectionBindToChain<S, View<HTMLElement>>` _(inherited)_

Binds and synchronizes the collection with another one.

The binding can be a simple factory:

```typescript
class FactoryClass {
	public label: string;

	constructor( data: { label: string } ) {
		this.label = data.label;
	}
}

const source = new Collection<{ label: string }>( { idProperty: 'label' } );
const target = new Collection<FactoryClass>();

target.bindTo( source ).as( FactoryClass );

source.add( { label: 'foo' } );
source.add( { label: 'bar' } );

console.log( target.length ); // 2
console.log( target.get( 1 ).label ); // 'bar'

source.remove( 0 );
console.log( target.length ); // 1
console.log( target.get( 0 ).label ); // 'bar'
```

or the factory driven by a custom callback:

```typescript
class FooClass {
	public label: string;

	constructor( data: { label: string } ) {
		this.label = data.label;
	}
}

class BarClass {
	public label: string;

	constructor( data: { label: string } ) {
		this.label = data.label;
	}
}

const source = new Collection<{ label: string }>( { idProperty: 'label' } );
const target = new Collection<FooClass | BarClass>();

target.bindTo( source ).using( ( item ) => {
	if ( item.label == 'foo' ) {
		return new FooClass( item );
	} else {
		return new BarClass( item );
	}
} );

source.add( { label: 'foo' } );
source.add( { label: 'bar' } );

console.log( target.length ); // 2
console.log( target.get( 0 ) instanceof FooClass ); // true
console.log( target.get( 1 ) instanceof BarClass ); // true
```

or the factory out of property name:

```typescript
const source = new Collection<{ nested: { value: string } }>();
const target = new Collection<{ value: string }>();

target.bindTo( source ).using( 'nested' );

source.add( { nested: { value: 'foo' } } );
source.add( { nested: { value: 'bar' } } );

console.log( target.length ); // 2
console.log( target.get( 0 ).value ); // 'foo'
console.log( target.get( 1 ).value ); // 'bar'
```

It's possible to skip specified items by returning null value:

```typescript
const source = new Collection<{ hidden: boolean }>();
const target = new Collection<{ hidden: boolean }>();

target.bindTo( source ).using( item => {
	if ( item.hidden ) {
		return null;
	}

	return item;
} );

source.add( { hidden: true } );
source.add( { hidden: false } );

console.log( source.length ); // 2
console.log( target.length ); // 1
```

**Note**: [`clear`](#function-clear) can be used to break the binding.

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

#### Type parameters

* `S: extends Record<string, any>`

  The type of `externalCollection` element.

#### Parameters

* `externalCollection: Collection<S>`

  A collection to be bound.

#### Returns

* `CollectionBindToChain<S, View<HTMLElement>>`

  The binding chain object.

<a id="function-clear">

### `clear() → void` _(inherited)_

Removes all items from the collection and destroys the binding created using [`bindTo`](#function-bindTo).

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

#### Returns

* `void`

#### Fires

* [remove](#event-remove)
* [change](#event-change)

<a id="function-delegate">

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

Delegates selected events coming from within views in the collection to any [`Emitter`](module_utils_emittermixin-Emitter.md).

For the following views and collection:

```typescript
const viewA = new View();
const viewB = new View();
const viewC = new View();

const views = parentView.createCollection();

views.delegate( 'eventX' ).to( viewB );
views.delegate( 'eventX', 'eventY' ).to( viewC );

views.add( viewA );
```

the `eventX` is delegated (fired by) `viewB` and `viewC` along with `customData`:

```typescript
viewA.fire( 'eventX', customData );
```

and `eventY` is delegated (fired by) `viewC` along with `customData`:

```typescript
viewA.fire( 'eventY', customData );
```

See [`delegate`](module_utils_emittermixin-Emitter.md#function-delegate).

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

#### Parameters

* `events: Array<string>`

  [`View`](module_ui_view-View.md) event names to be delegated to another [`Emitter`](module_utils_emittermixin-Emitter.md).

#### Returns

* `EmitterMixinDelegateChain`

  Object with `to` property, a function which accepts the destination of [delegated](module_utils_emittermixin-Emitter.md#function-delegate) events.

<a id="function-destroy">

### `destroy() → void`

Destroys the body collection: destroys its views and removes their shared container from the DOM. Use this method when you do not need the body collection anymore. For a reversible removal that keeps the views so the collection can be [attached](#function-attachToDom) again, use [`unmountFromDom`](#function-unmountFromDom) instead.

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

#### Returns

* `void`

<a id="function-filter">

### `filter( callback, ctx? ) → Array<View<HTMLElement>>` _(inherited)_

Returns an array with items for which the `callback` returned a true value.

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

#### Parameters

* `callback: ( item: View, index: number ) => boolean`

* `ctx?: any`

  Context in which the `callback` will be called.

#### Returns

* `Array<View<HTMLElement>>`

  The array with matching items.

<a id="function-find">

### `find( callback, ctx? ) → View<HTMLElement> | undefined` _(inherited)_

Finds the first item in the collection for which the `callback` returns a true value.

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

#### Parameters

* `callback: ( item: View, index: number ) => boolean`

* `ctx?: any`

  Context in which the `callback` will be called.

#### Returns

* `View<HTMLElement> | undefined`

  The item for which `callback` returned a true value.

<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-forEach">

### `forEach( callback, ctx? ) → void` _(inherited)_

Performs the specified action for each item in the collection.

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

#### Parameters

* `callback: ( item: View, index: number ) => unknown`

* `ctx?: any`

  Context in which the `callback` will be called.

#### Returns

* `void`

<a id="function-get">

### `get( idOrIndex ) → View<HTMLElement> | null` _(inherited)_

Gets an item by its ID or index.

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

#### Parameters

* `idOrIndex: string | number`

  The item ID or index in the collection.

#### Returns

* `View<HTMLElement> | null`

  The requested item or `null` if such item does not exist.

<a id="function-getIndex">

### `getIndex( itemOrId ) → number` _(inherited)_

Gets an index of an item in the collection. When an item is not defined in the collection, the index will equal -1.

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

#### Parameters

* `itemOrId: string | View<HTMLElement>`

  The item or its ID in the collection.

#### Returns

* `number`

  The index of a given item.

<a id="function-has">

### `has( itemOrId ) → boolean` _(inherited)_

Returns a Boolean indicating whether the collection contains an item.

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

#### Parameters

* `itemOrId: string | View<HTMLElement>`

  The item or its ID in the collection.

#### Returns

* `boolean`

  `true` if the collection contains the item, `false` otherwise.

<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-map">

### `map( callback, ctx? ) → Array<U>` _(inherited)_

Executes the callback for each item in the collection and composes an array or values returned by this callback.

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

#### Type parameters

* `U`

  The result type of the callback.

#### Parameters

* `callback: ( item: View, index: number ) => U`

* `ctx?: any`

  Context in which the `callback` will be called.

#### Returns

* `Array<U>`

  The result of mapping.

<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-remove">

### `remove( subject ) → View` _(inherited)_

Removes a child view from the collection. If the [parent element](#function-setParent) of the collection has been set, the [element](module_ui_view-View.md#member-element) of the view is also removed in DOM, reflecting the order of the collection.

See the [`add`](#function-add) method.

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

#### Parameters

* `subject: string | number | View<HTMLElement>`

  The view to remove, its id or index in the collection.

#### Returns

* `View`

  The removed view.

<a id="function-setParent">

### `setParent( elementOrDocFragment ) → void` _(inherited)_

Sets the parent HTML element of this collection. When parent is set, [adding](#function-add) and [removing](#function-remove) views in the collection synchronizes their [elements](module_ui_view-View.md#member-element) in the parent element.

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

#### Parameters

* `elementOrDocFragment: DocumentFragment | HTMLElement`

  A new parent element or document fragment.

#### 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-syncMountTarget">

### `syncMountTarget( target ) → void`

Keeps the collection mounted in the given target: attaches it there when the target differs from the current [`mountTarget`](#member-mountTarget) (see [`attachToDom`](#function-attachToDom)), unmounts it on a `null` target (see [`unmountFromDom`](#function-unmountFromDom)), and leaves the DOM untouched when the collection already sits in the target.

Designed for repeated calls with a freshly resolved target (for example on every editor UI update, or with the result of [`getOverlayMountRoot`](module_utils_dom_getoverlaymountroot.md#function-getOverlayMountRoot)), as opposed to [`attachToDom`](#function-attachToDom), which re-appends the container even when the target did not change.

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

#### Parameters

* `target: ShadowRoot | HTMLElement | null`

  The element or shadow root to mount the body collection in, or `null` to unmount it.

#### Returns

* `void`

<a id="function-unmountFromDom">

### `unmountFromDom() → void`

Removes the collection's container from the DOM without destroying its views, so it can be attached again later with [`attachToDom`](#function-attachToDom) – for example when the editor is temporarily disconnected from the document. For permanent teardown use [`destroy`](#function-destroy) instead.

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

#### Returns

* `void`

<a id="function-_removeFromDom">

### `_removeFromDom() → void` _(private)_

Removes the collection's container (and the shared wrapper, if now empty) from the DOM, keeping the container instance so it can be re-attached.

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

#### Returns

* `void`

#### Static methods

<a id="static-function-_getBodyWrapper">

### `_getBodyWrapper( mountTarget ) → HTMLElement` _(private)_

Returns the shared wrapper element for the given mount target, creating (and attaching) it if it does not exist yet or is no longer contained by the target. Body collections sharing a target share a wrapper.

The staleness check asks whether the target still contains the wrapper rather than testing `isConnected`, so a wrapper stays reused when the target itself is legitimately detached from the document (for example a configured [`ui.overlayContainer`](module_core_editor_editorconfig-UiConfig.md#member-overlayContainer) that is inserted later). Testing `isConnected` there would treat the still-attached wrapper as stale and build a duplicate wrapper for every body collection sharing that target.

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

#### Parameters

* `mountTarget: ShadowRoot | HTMLElement`

  The element or shadow root the wrapper is (or should be) attached to.

#### Returns

* `HTMLElement`

<a id="static-function-_removeBodyWrapperIfEmpty">

### `_removeBodyWrapperIfEmpty( mountTarget? ) → void` _(private)_

Removes the shared wrapper for the given mount target (and forgets it) once it holds no more body collections.

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

#### Parameters

* `mountTarget?: ShadowRoot | HTMLElement`

  The element or shadow root the wrapper is attached to.

#### Returns

* `void`

<a id="events">

## Events

<a id="event-add">

### `add( eventInfo, item, index )` _(inherited)_

Fired when an item is added to the collection.

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

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `item: T`

  The added item.

* `index: number`

  An index where the addition occurred.

<a id="event-change">

### `change( eventInfo, data )` _(inherited)_

Fired when the collection was changed due to adding or removing items.

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

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `data: CollectionChangeEventData<T>`

  Changed items.

<a id="event-remount">

### `remount( eventInfo )`

Fired when the collection's [mount target](#member-mountTarget) changes – it is [attached](#function-attachToDom), re-attached to a different target, or [unmounted](#function-unmountFromDom).

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

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

<a id="event-remove">

### `remove( eventInfo, item, index )` _(inherited)_

Fired when an item is removed from the collection.

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

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `item: T`

  The removed item.

* `index: number`

  Index from which item was removed.

---

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