Users

The Users plugin and related plugins let you manage user data and permissions. This is essential when many users are working on the same document.

# Additional feature information

The users plugin is automatically provided if you load any collaboration features plugins.

You must set the users data before you load the collaboration features. To do that, create a plugin that requires all collaboration features you use and defines the users.

// An example of a plugin that provides user data for an editor
// that uses the `Comments` and `RevisionHistory` plugins.
class UsersIntegration extends Plugin {
    static get requires() {
        return [ 'Comments', 'RevisionHistory' ];
    }

    init() {
        const users = this.editor.plugins.get( 'Users' );

        // Provide user data from your database.
        users.addUser( {
            id: 'u1',
            name: 'Zee Croce'
        } );

        users.addUser( {
            id: 'u2',
            name: 'Mex Haddox'
        } );

        // Define the local user.
        users.defineMe( 'u1' );
    }
}

// More code.
// ...

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        extraPlugins: [ UsersIntegration ],
        // More editor's configuration.
        // ...
    } );

# Local user (“me” user)

A local user (also called “me” user) is regarded as the one who uses the editor instance. Features (like comments or revisions history) will attribute changes to that user.

You can access the “me” user via Users plugin:

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

    // We get either `User` or `undefined` if the local user is not set.
    const localUser = usersPlugin.me;

You can also use the isMe flag on the User item to check if it is the local user:

    const id = 'e1d1a156789abc92e4b9affff124455bb';
    const user = editor.plugins.get( 'Users' ).getUser( id );

    // It is `true` if it is the "me" user, `false` otherwise.
    const isOwnUser = user.isMe; 

The local user’s avatar is highlighted in all places it is displayed. You can easily override this behavior using the .ck-user_me CSS class selector.

    /* Display the local user the same as other users. */
    .ck-user.ck-user_me {
        border: none;
        outline: none;
    }

# Anonymous user

If for some reason you do not want to, or you cannot, provide the user data, you can use the anonymous user:

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

usersPlugin.useAnonymousUser();

usersPlugin.me.name; // 'Anonymous'
usersPlugin.me.id; // 'anonymous-user'

The anonymous user’s avatar is a contour of a human face.

You can set the anonymous user’s ID using the config.users.anonymousUserId property:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // More editor's configuration.
        // ...
        users: {
            anonymousUserId: '0'
        }
    } );

# User permissions

In many applications, the document creation workflow consists of several precisely defined steps such as content creation, discussion, proofreading, final review and acceptance, etc. The users of such an application may have certain roles and permissions.

You can change the permissions for a given user, which results in enabling or disabling some editor functionalities.

You can set the permissions using the Permissions plugin. It is automatically provided if you load any of the collaboration features plugins.

It is a good practice to set permissions directly after defining the users:

class UsersIntegration extends Plugin {
    // More methods.
    // ...

    init() {
        const users = this.editor.plugins.get( 'Users' );

        // Provide user data from your database.
        users.addUser( {
            id: 'u1',
            name: 'Zee Croce'
        } );

        users.addUser( {
            id: 'u2',
            name: 'Mex Haddox'
        } );

        // Define the local user.
        users.defineMe( 'u1' );

        // Set permissions.
        const permissions = this.editor.plugins.get( 'Permissions' );

        // "Commentator" role.
        permissions.setPermissions( [
            'comment:write'
        ] );
    }
}

The full list of defined permissions is available in the Permissions plugin description.

# Operation authors

The Users#getOperationAuthor() method gives you the ability to check which user created a given operation. This is useful when creating custom features in integrations using real-time collaboration.

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 that are not meaningful (NoOperations).

Below is an example of using getOperationAuthor() to find out which user was the last to edit the document. 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 );
    }
} );

# Theme customization

# User avatar

You can define the user’s avatar appearance by modifying these CSS variables:

:root {
    --ck-user-avatar-size: 40px;
    --ck-user-avatar-background: hsl(210, 52%, 44%);
    --ck-user-name-color: hsl(0, 0%, 100%);

    /* Border color used to highlight the local user. */
    --ck-user-me-border-color: hsl(0, 0%, 100%);
}

# User colors

You can also 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 the 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, among others, used in the users presence list to represent users.

# Adding more user colors

You can define additional colors for users if you find the default set too small.

First, prepare a CSS file with some color definitions:

// mycolors.css

/* Import the "userColor" mixin to create definitions easily. */
@import "@ckeditor/ckeditor5-collaboration-core/theme/usercolormixin.css";

/**
 * Add some new definitions. The parameters for the "userColor" mixin are:
 *
 * - Color without an alpha channel (main color).
 * - Color with an alpha channel (selection marker color).
 * - Color ordering number.
 */
@mixin userColor hsla(31, 90%, 43%, 1), hsla(31, 90%, 43%, 0.15), 8;
@mixin userColor hsla(61, 90%, 43%, 1), hsla(61, 90%, 43%, 0.15), 9;

Then, import this CSS file and specify the colorsCount configuration option:

import './mycolors.css';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // More editor's configuration.
        // ...
        users: {
            colorsCount: 10
        }
    } );