# 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 [`detachFromDom`](#function-detachFromDom) will remove the collection from the DOM.

**Note**: The shared collection wrapper (`<div class="ck-body-wrapper">...</div>`) gets automatically removed from DOM when the last body collection is [detached](#function-detachFromDom) 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 | undefined` _(readonly)_

The element holding elements of the body collection.

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

<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-_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)

#### Static properties

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

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

The wrapper element that holds all of the [`_bodyCollectionContainer`](#member-_bodyCollectionContainer) elements.

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

<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#L86)

#### 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() → void`

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

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

#### 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` _(inherited)_

Destroys the view collection along with child views. See the view [`destroy`](module_ui_view-View.md#function-destroy) method.

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

#### Returns

* `void`

<a id="function-detachFromDom">

### `detachFromDom() → void`

Detaches the collection from the DOM structure. Use this method when you do not need to use the body collection anymore to clean-up the DOM structure.

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

#### 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: HTMLElement | DocumentFragment`

  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="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-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)