Cell Threaded Comments

Threaded Comments enable users to add contextual discussions to specific cells and reply to comments in threads. Each thread serves as a conversation container composed of replies, helping teams discuss, review, and resolve issues efficiently.

The example below shows how team members can use threaded comments to review a quarterly budget.

Key Benefits

• Enables collaboration and contextual feedback.

• Supports user mentions and hyperlinks in replies.

• Provides event-based integration and undo/redo support.

• Maintains compatibility with SpreadJS APIs and Excel export.

Dependencies

You can include the Threaded Comments either by referencing the all‑in‑one bundle or by loading the required sub‑modules individually.

Option 1 – Use the full package

If you reference the complete library file, such as:

<script src="gc.spread.sheets.all.<version>.min.js"></script>

Option 2 – Use modular packages

When you choose to include individual modules, make sure to load the following packages to enable the Threaded Comments feature:

<script src="gc.spread.sheets.comments.<version>.min.js"></script>
<script src="gc.spread.sheets.components.<version>.min.js"></script>
<script src="gc.spread.sheets.threadedcomments.<version>.min.js"></script>

Threaded Comments rely on the GC.Spread.Common.UserManager component to identify the current user who creates or replies to a comment.

If no user is explicitly configured, a default Guest user is generated automatically.

To learn how to configure and manage users globally, see User Management Feature.

Comment vs. Threaded Comment

Before diving into the structure and APIs, let’s clarify how threaded comments differ from the traditional cell comments (notes) in SpreadJS.

Architecture Overview

The following table summarizes the core components of the threaded comment architecture.

User Interface Operations

These operations are available through the UI and are also accessible via the related APIs.

Detailed Functionality

Events

Collaboration Model

• Editors can add, edit, delete, and resolve threaded comments.

• Viewers have read‑only access (no operator buttons or reply editor).

Mentions (@)

• Users can mention collaborators in replies using @username.

• The UserMentioned event triggers when mentions are added.

• The mention list supports up to 20 users.

Resolved State

Threads include a resolved flag.

• Purple Flag: Unresolved

• Gray Flag: Resolved

Comment Behavior & Limitations

Editing Rules

• Multiple threaded comments can be edited at the same time.

• Unsaved edits are discarded when the comment is hidden.

• No explicit editing‑state flag is maintained.

Mentions and Links

• Clicking a mention (@user) does not open a user information card.

• Hyperlink editing behavior varies by browser:

  • Safari: Automatically converts a pasted or typed URL to a hyperlink after posting.

  • Other browsers: Convert text to hyperlinks when Space or Enter is pressed.

Export and Compatibility Limits

• When exporting to Excel, user IDs must comply with the UUID format:

  {XXXXXXXX‑XXXX‑XXXX‑XXXX‑XXXXXXXXXXXX}

• If a user ID does not meet this format, SpreadJS adjusts it to fit Excel’s specification.

  This may result in loss of edit permissions after re‑import because the user ID changes.

Structural Limitation

Threaded comments currently do not support nested structures; all replies remain at a single (flat) level.

Presence Limitation

Threaded comments do not support real‑time presence or live editing indicators.

Keyboard Shortcuts

The following keyboard shortcuts are available when working with threaded comments:

Underlying APIs

Threaded Comments rely on several key classes and events within SpreadJS.

Core Objects

Additional Support

GC.Spread.Sheets.Search and GC.Spread.Sheets classes extend common operations—search, copy, cut, clear, and used range—to include threaded‑comment data.

Using Code Examples

This section demonstrates several basic operations for threaded comments using the SpreadJS API.

Basic Example — Add a Comment

This creates a new threaded comment in cell E3 authored by the current user.

The comment indicator automatically appears on the cell.

// Initialize workbook
const spread = new GC.Spread.Sheets.Workbook("ss");
const sheet = spread.getActiveSheet();

// Define user info
var users = [
        { id: "user1", name: "Alice Johnson", email: "alice.johnson@company.com",},
        { id: "user2", name: "Bob Smith", email: "bob.smith@company.com",}
    ];
GC.Spread.Common.UserManager.configure({
    get: async (userId) => {
        if (userId === undefined) {
            return;
        }
        return new Promise((resolve) => {
            const user = users.find(u => u.id === userId);
            resolve(user);
        });
    },
    search: async (query) => {
        return new Promise((resolve) => {
            resolve(users.filter(u => 
                        u.name.toLowerCase().includes(query.toLowerCase()) || 
                        u.email.toLowerCase().includes(query.toLowerCase())
                    ));
        });
    }
});

// Set current user
GC.Spread.Common.UserManager.current("user1");

// Create a comment
const comment_1 = {
    message: [
       { type: GC.Spread.Sheets.ThreadedComments.ContentType.text, value: "Hey " },
       { type: GC.Spread.Sheets.ThreadedComments.ContentType.mention, userId: "user2" },
       { type: GC.Spread.Sheets.ThreadedComments.ContentType.text, value: ", please review the budget variance in Development department: " },
       { type: GC.Spread.Sheets.ThreadedComments.ContentType.link, href: "https://example.com/budget-policy", text: "Budget Policy" }
    ],
    authorId: "user1",
    createdAt: new Date("2025-12-10T15:44:00")
};

// Add a threaded comment to cell B4
const threadedCommentManager = sheet.threadedComments;
const threadedComment = threadedCommentManager.add(2, 4);
threadedComment.add(comment_1);

Example — Update, Reply, Change Status, or Delete a Threaded Comment

This example builds on the previous sample.

// Get a specific thread
const thread = threadedCommentManager.get(2, 4);  
console.log(thread.row()); // Output: 2

// Create a reply
const reply_1 = {
    message: [
    {type: GC.Spread.Sheets.ThreadedComments.ContentType.text,
        value: "Confirmed. "
    }],
    authorId: "user2", 
    createdAt: new Date("2025-12-12T11:47:00")
};

// Add a reply
thread.add(reply_1);

// Edit an existing reply
thread.set(0,{ message: [{ type: GC.Spread.Sheets.ThreadedComments.ContentType.text, value: 'Please verify this value.' }] });

// Delete a reply
thread.remove(1);

// Resolve / reopen
thread.resolved(true)

Example — Handling Threaded Comment Events

Subscribe to events to trigger custom logic.

sheet.bind(GC.Spread.Sheets.Events.ThreadedCommentChanging, function (e, info) {
    // Handle threaded comment property or reply changes
});

sheet.bind(GC.Spread.Sheets.Events.UserMentioned, function (e, info) {
    console.log(args);
});