# Users in real-time collaboration

After you [enable the real-time collaborative editing](real-time-collaboration-integration.md) plugin, the selections of collaborating users will automatically display to all of them with no additional configuration. The editor will also set the proper permissions for the local user based on data received from the server.

There are even more user features that can be enabled in real-time collaboration. The package contains an easy-to-install plugin to show the list of connected users and the sessions API to observe this collection.

<a id="user-roles-and-permissions">

## User roles and permissions

CKEditor 5 supports setting user roles and permissions to enable/disable some editor functionalities for the user.

To learn how to define user roles and permissions, refer to the [Roles and permissions](../../../../../cs/latest/developer-resources/security/roles.md) guide of the Cloud Services documentation.

<a id="users-presence-list">

## Users presence list

The [`PresenceList`](../../../api/module_real-time-collaboration_presencelist-PresenceList.md) plugin provides a UI which displays all users that are currently connected to the edited document. The users are displayed as a row of avatars. The information about the users is provided by [CKEditor Cloud Services](../../../../../cs/latest/developer-resources/security/token-endpoint.md#user).

The presence list UI collapses to a dropdown if six or more users are connected.

By default, the local user avatar is always present on the list. You can hide it by setting the [`displayMe`](../../../api/module_real-time-collaboration_config-RtcPresenceListConfig.md#member-displayMe) configuration flag to `false`. It is also displayed in a different color and listed first.

<a id="installation-and-configuration">

### Installation and configuration

> **Note**
>
> Before you start, make sure that you go through the [Real-time collaboration features integration](real-time-collaboration-integration.md) guide. This section uses it as a starting point and assumes your real-time collaboration editor is working and the [`PresenceList`](../../../api/module_real-time-collaboration_presencelist-PresenceList.md) plugin is loaded.

The [plugin configuration](../../../api/module_real-time-collaboration_config-RtcPresenceListConfig.md) consists of the following options:

* `container` – This is a DOM element that will hold the feature’s UI. It is required and already defined if you use the code from the [Real-time collaboration features integration](real-time-collaboration-integration.md) tutorial.
* `collapseAt` – This optional parameter defines how many users need to be connected to switch the presence list to the dropdown view. The default value is `6`.
* `displayMe` – This optional flag defines whether the local user avatar is displayed in the presence list. The default value is `true`.
* `onClick` – Here, you can pass a callback function that will be invoked after a click in a presence list member. This function is invoked with two arguments: the `user` and the `element`. The first provides the clicked member details, and the second is the clicked element. This option is not required.
* `overlayContainer` – This optional parameter is a DOM element or a shadow root that will hold the presence list dropdown. Use it when the presence list is rendered inside a shadow root. Refer to the [API documentation](../../../api/module_real-time-collaboration_config-RtcPresenceListConfig.md#member-overlayContainer) for details.

You can add the following code to the editor configuration object to get more control over the user presence list:

```js
const editorConfig = {
	/* ... */

	presenceList: {
		// Existing configuration.
		container: document.querySelector('#editor-presence'),

		// Additional configuration.
		collapseAt: 3,
		onClick: ( user, element ) => console.log( user, element )
	},

	/* ... */
}
```

> **Note**
>
> Complementary to this guide, we provide [ready-to-use **samples** available for download](https://github.com/ckeditor/ckeditor5-collaboration-samples/). We prepared samples for all editor types (multi-root included) as well as for the React, Angular, and Vue integrations. You may use them as an example or as a starting point for your integration.

<a id="theme-customization">

### Theme customization

The user presence list feature uses [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables), so you can customize its appearance without changing its source styles.

By default a presence list has two states with a dedicated design:

* Avatars displayed inline in the container (with fewer than 6 users connected).
* A dropdown panel (with 6 or more users connected). You can change this number with the `collapseAt` option.

<a id="example-of-presence-list-customization-with-css-variables">

### Example of presence list customization with CSS Variables

With [inheritance of CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables#Inheritance_of_CSS_Variables) you can change the default values of variables. You can override these properties with a `.css` file or place your customizations directly into the `<head>` section of your page, but in this case, you will need to use a more specific CSS selector than `:root` (like `<body>`).

If the editor is mounted inside a shadow root, override the variables on the shadow `:host` element instead, as described in the [Shadow DOM](../../../getting-started/setup/shadow-dom.md#overriding-css-variables) guide.

Add the following styles to the `style.css` file created in the [Real-time collaboration features integration](real-time-collaboration-integration.md) guide:

```css
/* Change the user presence list hue to greenish and make the local user avatar stand out. */
.ck.ck-presence-list {
	--ck-user-avatar-background-color: #215a11;
	--ck-user-me-avatar-background-color: #b45309;
}

.ck.ck-presence-list__balloon {
	/* Make a smaller user avatar in the dropdown list. */
	--ck-presence-list-dropdown-avatar-size: 25px;

	--ck-user-avatar-background-color: #215a11;
	--ck-user-me-avatar-background-color: #b45309;
	--ck-presence-list-dropdown-background-color: #d0ecd2;
	--ck-presence-list-dropdown-border-color: #a6d3aa;
	--ck-presence-list-hover-background-color: #bce0bf;
}

.ck.ck-presence-list__balloon .ck.ck-presence-list__dropdown-list-wrapper {
	/* Reduce the minimum and maximum width of the dropdown. */
	--ck-presence-list-dropdown-list-min-width: 100px;
	--ck-presence-list-dropdown-list-max-width: 150px;
}
```

> **Note**
>
> Check out the [color token files](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-ui/theme/globals/colors) for the full list of customizable colors. You can also browse [other files](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-ui/theme/globals) with CSS Variables in CKEditor 5.

To change the color assigned to users, refer to the [Users API](../users.md#theme-customization) guide.

The examples above will generate the following presence list designs:

<a id="sessions">

## Sessions

The [`Sessions`](../../../api/module_real-time-collaboration_realtimecollaborativeediting_sessions-Sessions.md) plugin stores information about users and sessions connected to the rich text editor. You may say that the presence list is a visualization of the sessions plugin data.

The difference between the sessions plugin and the [users plugin](../users.md) is that the latter also keeps information about the users who are not currently connected to the editor (for example, a comment author who is currently offline).

If your integration uses the [context feature](../context-and-collaboration-features.md) and there are multiple channels used, the `Sessions` plugin aggregates users connected to all the channels.

There are two types of entries in the sessions plugin: connected users and sessions.

There is one session for each connection to a given channel. For example, for each open editor instance connecting to a given channel ID, there will be a session. Every session has a user. However, the same user can be linked with multiple sessions (for example, the same user opened the same URL in multiple tabs).

In other words, if the same user (with the same user ID) opens the same document in two different tabs, they will create two sessions but only one user will be connected. You will be able to see two selections in the same document, both in the same color, but only a single user in the [user presence list](#users-presence-list).

<a id="sessions-api">

### Sessions API

If you use real-time collaboration features, the `Sessions` plugin will be loaded and available:

```js
const sessionsPlugin = editor.plugins.get( 'Sessions' );
```

Check the [API of the `Sessions` plugin](../../../api/module_real-time-collaboration_realtimecollaborativeediting_sessions-Sessions.md) to learn how to use it.

---

Full index of the CKEditor 5 documentation: [llms.txt](../../../../llms.txt)