Report an issue

guideUsers API

Users API is used by multiple collaboration plugins. Collaboration consists of working on the same document by multiple users, so information about these users needs to be stored in the editor. The comments feature needs to have comment authors defined and real-time collaborative features require the users plugin to handle collaborative users.

CKEditor 5 provides a special plugin to handle its users. The Users plugin will be provided if you load any plugins that require its API and will be available as:

const usersPlugin = editor.plugins.get( 'Users' );

# The basic API

The Users plugin provides the basic interface for setting and getting users.

/**
 * Adds a new user to the list of the editor users.
 *
 * @param userData {Object}
 * @returns {User}
 */
addUser() {}

/**
 * Returns the user with a given ID.
 *
 * @param {String} id
 * @returns {Object}
 */
getUser( id ) {}

/**
 * Sets the user with a given ID as a Users#me.
 *
 * @param userData {Object}
 * @returns {User}
 */
defineMe() {}

/**
 * Returns the author of the operation.
 * See the "Operation authors" section below.
 * 
 * @public
 * @param operation {Operation}
 *
 * @returns {User|null}
*/
getOperationAuthor( operation ) {}

/**
 * A reference to the currently connected user.
 *
 * @type {Object}
 */
get me() {}

/**
 * An iterable list of all users added to the editor.
 *
 * @type {Collection}
 */
get users() {}

For instance:

for ( const user of editor.plugins.get( 'Users' ).users ) {
    console.log( user.name );
}

Check the Collection API to see how to use the #users collection.

# Users#me

A reference to the currently connected user. Do not forget to set it using defineMe(), for example:

const usersPlugin = editor.plugins.get( 'Users' );

usersPlugin.addUser( {
    id: 'user-id',
    name: 'John Smith'
} );

usersPlugin.defineMe( 'user-id' );

Most of the collaboration plugins need this property to be defined.

Note that the real-time collaborative editing plugin will define it automatically based on your token data.

# Operation authors

Users#getOperationAuthor() gives you an ability to check which user created given operation. This is useful for integrations using real-time collaboration, when creating custom features.

There are two cases when the operation author might be null:

  1. For initial operations (fetched from the server when connecting).
  2. For some automatically created operations which aren’t meaningful (NoOperations).

Below is an example of using getOperationAuthor(): finding out which user was the last to edit the document. Note that in this case you should skip NoOperations and some MarkerOperations since they do not affect the document content.

let lastUser = null;

editor.model.on( 'applyOperation', ( evt, args ) => {
    const users = editor.plugins.get( 'Users' );
    const operation = args[ 0 ];

    if ( operation.isDocumentOperation && affectsData( operation ) ) {
        const user = users.getOperationAuthor( operation );

        if ( user && user != lastUser ) {
            lastUser = user;

            console.log( lastUser.name, lastUser, operation );
        }
    }

    function affectsData( operation ) {
        return operation.type != 'noop' && ( operation.type != 'marker' || operation.affectsData );
    }
} );

# User object

A single user is represented by the following object:

{
    /**
     * The ID of the user.
     *
     * @type {String}
     */
    get id() {}

    /**
     * The name of the user.
     *
     * @type {String}
     */
    get name() {}

    /**
     * The initials of the user.
     * When the name is `Joe Doe`, the initialis are `JD`.
     *
     * @type {String}
     */
    get initials() {}

    /**
     * The avatar URL of the user.
     *
     * @type {String|undefined}
     */
    get avatar() {}

    /**
     * Is `true` when the user name is not provided and it is
     * automatically set as `Anonymous`, `false` otherwise.
     *
     * @type {Boolean}
     */
    get isAnonymous() {}

    /**
     * The color object used to generate specified CSS classes
     * with an idividual color number assigned to the user.
     * See the "Theme customization" section to know how to change
     * the user colors.
     */
    color: {
        /**
         * Returns `ck-user__bg-color--${ number }` where the number is
         * an individual color number assigned to the user.
         *
         * @returns {String}
         */
        getBackgroundColorClass() {}

        /**
         * Returns `ck-user__selection--${ number }` where the number is
         * an individual color number assigned to the user.
         *
         * @returns {String}
         */
        getSelectionClass() {}

        /**
         * Returns `ck-user__marker--${ number }` where the number is
         * an individual color number assigned to the user.
         *
         * @returns {String}
         */
        getMarkerClass() {}
    }
}

# 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.

/* The 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 users presence list to represent users.