userlookup.adoc

User Lookup API

The {productname} User Lookup API allows you to retrieve and cache user details, such as names and avatars, and identify the current user within the editor.

This is useful when building features that rely on user context, such as commenting, collaborative editing, or displaying user-specific information. The API provides built-in caching for efficient user data management, as well as fallback user data when none is provided.

Properties and Methods

The User Lookup API serves two purposes, to identify the current user and to fetch user details for other users. These can be configured to suit your application through the user_id and fetch_users options respectively.

The User Lookup API provides properties and methods through the editor.userLookup object, which is available after the editor is initialized.

API	Type	Return Type
editor.userLookup.userId	Property	string
editor.userLookup.fetchUsers(userIds)	Method	Object<string, Promise<UserObject>>

editor.userLookup.userId

Returns the current user’s ID, set via the user_id configuration option. This is a string that uniquely identifies the user in the context of the editor, such as a username or an email address. If the user_id option is not set, it defaults to 'Anonymous'.

editor.userLookup.fetchUsers

Fetches and caches user information for the specified user IDs. This method accepts an array of user IDs and returns an object where each key is a user ID and each value is a Promise that resolves to the user object. If a user ID is not found, the Promise will reject with an error message.

The user object

The user is an Object that contains the following fields:

Field	Type	Required?	Description
id	string	required	The unique string ID of the user.
name	string	optional	The display name of the user. If not provided, defaults to the id.
avatar	string	optional	The URL of the user’s avatar image or data URI. If not provided, an auto-generated SVG using the user’s initials will be used.
custom	Object	optional	Additional metadata for the user. This can include any custom fields relevant to your application, such as roles or permissions.

Example user object:

{
  id: 'user-1',           // Required: User identifier
  name: 'Jane Doe',       // Optional: Display name (defaults to id)
  avatar: 'https://...',  // Optional: Avatar URL or data URI
  custom: {               // Optional: Additional metadata
    role: 'admin',
    department: 'engineering'
  }
}

Options

The following configuration options affect the behavior of the User Lookup API.

partial$configuration/user_id.adoc

partial$configuration/fetch_users.adoc

Usage Examples

Basic setup

For a basic setup, configuring the user_id option allows you to identify the current user. The fetch_users option can be omitted, and {productname} will provide fallback user data.

tinymce.init({
  selector: '#editor',
  user_id: 'alextaylor'
});

Complete setup with fetch_users

This example demonstrates how to simulate user lookup in-browser. In a production environment, the fetch_users function would typically make network requests to your backend API.

Example

const userDb = {
  'janedoe': {
    id: 'janedoe',
    name: 'Jane Doe',
    avatar: 'https://example.com/avatar/jane.png'
  },
  'johnsmith': {
    id: 'johnsmith',
    name: 'John Smith'
  },
  'alextaylor': {
    id: 'alextaylor',
    name: 'Alex Taylor',
    avatar: 'https://example.com/avatar/alex.png'
  }
};

tinymce.init({
  selector: '#editor',
  user_id: 'alextaylor',
  fetch_users: (userIds) => {
    return Promise.all(
      userIds.map(
        (userId) => new Promise(
          (resolve) => resolve(userDb[userId] || { id: userId }) // Return user data or a fallback object if not found
        )
      )
    )
  },
});

Note	It is recommended to handle (or catch) promise rejections in the fetch_users function by providing fallback data. This will ensure that your application can gracefully handle cases where user data is not found or the network request fails.

Basic usage

Once the editor is initialized, you can access the current user ID and fetch user information:

editor.on('init', () => {
  // Get the current user ID
  const currentUserId = editor.userLookup.userId;
  console.log('Current user:', currentUserId);

  // Fetch user information
  const users = editor.userLookup.fetchUsers([ currentUserId ]);

  users[currentUserId].then((user) => {
    console.log('Current user name:', user.name);
  });

  // Handle multiple users
  Promise.all(Object.values(users)).then((allUsers) => {
    allUsers.forEach((user) => {
      console.log(`Fetched: ${user.name} (${user.id})`);
    });
  });
});

Advanced usage with UI example

This example shows how to create a toolbar button that displays the current user’s information:

tinymce.init({
  selector: '#editor',
  user_id: 'alextaylor',
  setup: (editor) => {
    editor.ui.registry.addButton('show-user', {
      text: 'Show User',
      onAction: () => {
        const currentUser = editor.userLookup.userId;
        const users = editor.userLookup.fetchUsers([ currentUser ]);

        users[currentUser].then((user) => {
          editor.notificationManager.open({
            text: `Logged in as: ${user.name}`,
            type: 'info'
          });
        });
      }
    });
  },
  toolbar: 'show-user'
});

Fallback Behavior

If no fetch_users function is configured, {productname} will return fallback users with auto-generated data:

• name defaults to the user ID

• avatar is an auto-generated SVG using the first letter of the name

This is useful for simpler setups or prototyping:

tinymce.init({
  selector: '#editor',
  user_id: 'alextaylor'
});

editor.on('init', () => {
  const users = editor.userLookup.fetchUsers(['alextaylor']);
  users['alextaylor'].then((user) => {
    console.log('Generated fallback user:', user);
  });
});