Report an issue

guideUsers in real-time collaboration

After you enable the real-time collaborative editing plugin, the selections of the collaborating users should automatically be displayed to all of them. No additional configuration is needed.

Also, after connecting to the server, the editor will automatically set the proper mode depending on the role of me received from the server (reader, writer or commentator). User roles specify the actions that the user can do in the rich-text editor. To learn more, read about the comments-only mode and the read-only mode.

User selections shown in real-time collaboration for CKEditor 5 WYSIWYG editor.

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.

# User roles

CKEditor 5 supports CKEditor Cloud Services user roles. Depending on the assigned role, the user has different permissions:

  • Reader – The editor is set to the read-only mode and the user can only read the document.
  • Commentator – The editor is set to the comments-only mode and the user can also add comments to the document.
  • Writer – The user has full access to read, write, modify and comment the content.

More information about user roles can be found in the Roles guide of the CKEditor Cloud Services documentation.

# Users presence list

The PresenceList 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.

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

Real-time collaboration user presence list in CKEditor 5 WYSIWYG editor.

Complementary to this guide, we provide ready-to-use samples available for download. 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 own integration.

# Installation and configuration

The presence list feature requires the RealTimeCollaborativeEditing plugin to work.

Before you start, make sure that you are already familiar with the Real-time collaboration features integration guide.

The presence list feature also needs the PresenceList plugin to be included in your build. If you are using the build from the Real-time collaborative features integration, it is already included. If you are creating your custom build in any other way, you need to include it manually now.

When you have the PresenceList plugin included in your custom build, you can add the HTML structure and initialize the editor.

Note that you do not need to manually import the RealTimeCollaborativeEditing plugin anymore. The presence list plugin requires it and will enable it automatically. All you need to do is add the PresenceList plugin to the list of included plugins.

The plugin configuration consists of three options:

  • container – This is a DOM element that will hold the feature’s UI. It is required.
  • collapseAt – This optional parameter defines how many users need to be connected in order to switch the presence list to the dropdown view. The default value is 6.
  • onClick – There you can pass a callback function that will be invoked after a click on 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.

This is what the updated sample from the Real-time collaborative features integration tutorial with the presence list added looks like:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>CKEditor 5 Collaboration – Hello World!</title>
    </head>

    <div id="presence-list-container"></div>

    <div id="editor"></div>

    <script src="../build/ckeditor.js"></script>
    <script>
        ClassicEditor.create( document.querySelector( '#editor' ), {
            initialData: '<p>Let\'s edit this together!</p>',
            toolbar: [ 'bold', 'italic', 'imageUpload' ],
            plugins: [ 'Essentials', 'Paragraph', 'Bold', 'Italic', 'EasyImage', 'RealTimeCollaborativeEditing', 'PresenceList' ],
            cloudServices: {
                // PROVIDE CORRECT VALUES HERE:
                tokenUrl: 'https://example.com/cs-token-endpoint',
                uploadUrl: 'https://your-organization-id.cke-cs.com/easyimage/upload/',
                webSocketUrl: 'your-organization-id.cke-cs.com/ws/',
                documentId: 'collaboration'
            },
            presenceList: {
                container: document.querySelector( '#presence-list-container' ),
                collapseAt: 3,
                onClick: ( user, element ) => console.log( user, element )
            }
        } )
        .catch( error => console.error( error ) );
    </script>
</html>

This is all. You should now see the user presence list above the rich-text editor.

# Theme customization

Like in the whole CKEditor 5 Ecosystem PostCSS is used to handle styles with the power of CSS Variables. The user presence list feature also uses it to make it possible to easily customize its appearance.

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

  • Avatars displayed inline in the container (with fewer than 5 users).
  • A dropdown panel for more than 5 users connected.

# Example of presence list customization with CSS Variables

With Inheritance of CSS Variables you can change the default values of variables. You can easily 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 (e.g. <body>).


/* Change the user presence list hue to greenish. */
.ck.ck-presence-list {
    --ck-user-avatar-background: #215a11;
}

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

    --ck-user-avatar-background: #215a11;
    --ck-color-presence-list-dropdown-background: #d0ecd2;
    --ck-color-presence-list-dropdown-arrow-border: #d0ecd2;
}

.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;
}

Check out the color sheet for the full list of customizable colors. You can also browse other files with CSS Variables in CKEditor 5.

If you want to change the color assigned to users, refer to the Users API guide.

The examples above will generate the following presence list designs:

Custom CSS Variables in the user presence list for CKEditor 5 WYSIWYG editor.

# Sessions

The presence list is a visualization of user sessions. The Sessions plugin stores the information about users and sessions connected to the rich-text editor. This distinguishes it from the Users plugin which may also keep information about the users who are not connected to the editor at the moment, for instance the comment authors.

The Sessions plugin provides two collections: the currently connected users and their sessions. It also contains a few methods for getting individual users and sessions.

The sessions collection is very similar to the users collection, and the difference between them can be easily explained with an example. If a single user (with the same user ID) opens the same document in two browsers or two browser tabs, they will create two sessions but only one user will be connected. You will be able to see two selections on the same document, both in the same color, but only a single user in the user presence list.

One user visible in collaboration with multiple sessions in CKEditor 5 WYSIWYG editor.

Note that there might be multiple references to the same user in the sessions collection. If you connect the same user to the same document in another tab, add will be fired on the sessions collection, but not on the connectedUsers collection.

If the CollaborativeEditing plugin is loaded, the Sessions plugin is loaded, too, and is available as:

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

The API of this plugin looks as follows:

/**
 * The observable collection of all sessions connected to the document.
 * A session is represented by an object with the
 * following properties:
 * * `id` - A unique session ID.
 * * `user` - A reference to the user.
 *
 * @type {module:utils/collection~Collection}
 */
get sessions() {}

/**
 * The observable collection of all collaborating users connected to the document.
 *
 * @type {module:utils/collection~Collection}
 */
get connectedUsers() {}

/**
 * A property with the local user's session ID.
 *
 * @type {String}
 */
get mySessionId() {}

/**
 * Returns a reference to the user that created a session with
 * the given ID.
 *
 * @param {String} sessionId The session ID for which the
 * user should be returned.
 * @returns {Object}
 */
getUserBySessionId( sessionId ) {}

/**
 * Returns all sessions created by the given user.
 *
 * @param {module:collaboration-core/users~Users} user The user object.
 * @returns {Array.<Object>} Returns the list of user sessions.
 */
getUserSessions( user ) {}

/**
 * Returns the given user role.
 *
 * @param {module:collaboration-core/users~Users} user The user object.
 * @returns {String}
 */
getUserRole( user ) {}

Check the Collection API to see how to use the sessions and connectedUsers collections.