Users API

CKEditor 5 provides an API to get information about connected users.

# Connected users collection

ConnectedUsers lets you get a collection of all connected users.

const connectedUsersPlugin = editor.plugins.get( 'ConnectedUsers' );
const connected = connectedUsersPlugin.connected;

for( const user of connected ) {
    console.log( user.name );    
}

The connected property is a collection of objects with all user properties encoded in the token when this user authenticates. Each User object has an obligatory id property with the user identifier and may have additional properties such as name, email or avatar if these were specified for that user.

Since the connected property implements the Collection interface, you are able to use its events:

connected.on( 'add', ( evt, user ) => {
    console.log( 'added user', user );
    console.log( 'all users', Array.from( connected ) );
} );

The ConnectedUsers plugin contains the me property that keeps the reference to the local user.

# Session collection

The ConnectedUsers plugin also provides the collection of sessions.

The difference between connected users and session 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 2 selections on the same document, both in the same color, but only a single user in the presence list.

The connected users plugins has a sessions property, which implements the Collection interface, too:

const connectedUsersPlugin = editor.plugins.get( 'ConnectedUsers' );
const sessions = connectedUsersPlugin.sessions;

sessions.on( 'add', ( evt, session ) => {
    console.log( 'new session id', session.id );
    console.log( 'user name', session.user.name );
} );

Each session object has 2 properties:

• A unique session ID.
• A reference to the user object.

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 connected collection.

connectedUsersPlugin has the mySessionId property with the local user’s session ID and the getUserSessions() method that returns all session IDs for the given user.

# Colors

As you can see, each user gets a dedicated color which is used to represent them, for instance when this user selects some text.

However, the color is not a property of the user. It is not defined when the user connects, and the same user may be seen in a different color from the perspective of two collaboration clients.

Colors are managed by a separate UserColors plugin. Using it you can get the CSS classes used for colors:

const userColorsPlugin = editor.plugins.get( 'UserColors' );
const connectedUsersPlugin = editor.plugins.get( 'ConnectedUsers' );

for( const user of connected ) {
    console.log( userColorsPlugin.get( user ).getMarkerClass() );
}

For each user color you can call the following methods:

• getBackgroundColorClass() – Returns ck-user__bg-color--${ number }.
• getSelectionClass() – Returns ck-user__selection--${ number }.
• getMarkerClass() – Returns ck-user__marker--${ number }.

# Theme customization

It is possible to define colors used to represent the selection of other users.

By default, 8 colors are defined for users. Like in the whole CKEditor 5 Ecosystem PostCSS is used to handle styles with the power of CSS Variables. With Inheritance of CSS Variables you can change the default colors.

A color with an alpha channel (--ck-user-colors--$(number)-alpha) is dedicated for selections (.ck .ck-user__selection--$(number)). The rest of the classes use colors defined as --ck-user-colors--$(number). Feel free to change this color palette to fit your UI.

/* Current color set for users in the collaboration plugins. */
:root {
    --ck-user-colors--0: hsla(235, 73%, 67%, 1);
    --ck-user-colors--0-alpha: hsla(235, 73%, 67%, 0.15);

    --ck-user-colors--1: hsla(173, 100%, 24%, 1);
    --ck-user-colors--1-alpha: hsla(173, 100%, 24%, 0.15);

    --ck-user-colors--2: hsla(0, 46%, 50%, 1);
    --ck-user-colors--2-alpha: hsla(0, 46%, 50%, 0.15);

    --ck-user-colors--3: hsla(256, 54%, 45%, 1);
    --ck-user-colors--3-alpha: hsla(256, 54%, 45%, 0.15);

    --ck-user-colors--4: hsla(95, 50%, 36%, 1);
    --ck-user-colors--4-alpha: hsla(95, 50%, 36%, 0.15);

    --ck-user-colors--5: hsla(336, 78%, 43%, 1);
    --ck-user-colors--5-alpha: hsla(336, 78%, 43%, 0.15);

    --ck-user-colors--6: hsla(0, 80%, 59%, 1);
    --ck-user-colors--6-alpha: hsla(0, 80%, 59%, 0.15);

    --ck-user-colors--7: hsla(184, 90%, 43%, 1);
    --ck-user-colors--7-alpha: hsla(184, 90%, 43%, 0.15);
}

These colors are also used in the presence list to represent users.

# Utilities

CKEditor 5 Collaboration Features additionally provide a set of simple but useful utilities for user management.

# getName

The getName() utility provides a trimmed name or a default name if the name is undefined or can be trimmed to a zero-length string.

import { getName } from '@ckeditor/ckeditor5-collaboration/src/users/utils';

getName( ' John ' ); // -> 'John'
getName( '  ' ); // -> 'Anonymous'

# isAnonymous

The isAnonymous() utility checks if the name is undefined or can be trimmed to a zero-length string.

import { isAnonymous } from '@ckeditor/ckeditor5-collaboration/src/users/utils';

isAnonymous( ' John ' ); // -> false
isAnonymous( '  ' ); // -> true

# getInitials

The getInitials() utility returns the first characters of the first 2 words from a given string.

import { getInitials } from '@ckeditor/ckeditor5-collaboration/src/users/utils';

getInitials( 'John Snow' ); // -> 'JS'
getInitials( `Daenerys Stormborn of the House Targaryen,
    First of Her Name, the Unburnt, Queen of the Andals and the First Men,
    Khaleesi of the Great Grass Sea, Breaker of Chains, and Mother of Dragons`
); // -> 'DS'