Users 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 editing requires 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 a user of given id as a Users#me.
 *
 * @param userData {Object}
 * @returns {User}
 */
defineMe() {}

/**
 * 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 );
}

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

# 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 presence list to represent users.