1. Spreadsheet docs
  2. Developers

Users, comments and collaboration

Tell the workbook who is using it, connect your user directory to comments and mentions, show where colleagues are, and run your own real-time collaboration server.

A workbook in your app knows nothing about your users until you tell it. With the user API you set who is editing, so new comments and undo steps carry the right name; connect your own directory, so @ mentions in threaded comments find your colleagues; and show where other people are working. Real-time co-editing goes through a collaboration server that you run.

Set the current user and the directory

JavaScript

import { mountWorkbook } from '@8sheets/core';

const wb = await mountWorkbook(document.querySelector('#sheet'));

wb.users.current = { id: 'u-17', name: 'Anna Nowak', email: 'anna@example.com' };

// Mentions in threaded comments search your own directory.
wb.users.connect({
  get: async (id) => (await fetch(`/api/users/${id}`)).json(),
  search: async (query) => (await fetch(`/api/users?q=${encodeURIComponent(query)}`)).json(),
});

wb.events.on('mentioned', (e) => notify(e.person));          // e.g. send an email
wb.events.on('comment-changed', (e) => saveSoon(e.sheet));

React

import { Sheet } from '@8sheets/react';

export function TeamWorkbook({ me, directory, notify }) {
  function setUp(wb) {
    wb.users.current = { id: me.id, name: me.name, email: me.email };
    wb.users.connect({ get: directory.get, search: directory.search });
  }

  return (
    <div style={{ height: 560 }}>
      <Sheet onReady={setUp} onMentioned={(e) => notify(e.person)} />
    </div>
  );
}

Vue

<script setup>
import { Sheet } from '@8sheets/vue';

const props = defineProps({ me: Object, directory: Object, notify: Function });

function setUp(wb) {
  wb.users.current = { id: props.me.id, name: props.me.name, email: props.me.email };
  wb.users.connect({ get: props.directory.get, search: props.directory.search });
}
</script>

<template>
  <Sheet style="height: 560px" @ready="setUp" @mentioned="(e) => props.notify(e.person)" />
</template>

Angular

import { Component, Input } from '@angular/core';
import { SheetComponent, SheetEventPayload, SheetsWorkbook } from '@8sheets/angular';

interface Person { id: string; name: string; email?: string }

@Component({
  selector: 'app-team-workbook',
  imports: [SheetComponent],
  template: `<eight-sheet class="grid" (ready)="setUp($event)" (mentioned)="onMention($event)" />`,
  styles: `.grid { height: 560px; }`,
})
export class TeamWorkbook {
  @Input() me!: Person;
  @Input() search!: (query: string) => Promise<Person[]>;

  setUp(wb: SheetsWorkbook) {
    wb.users.current = this.me;
    wb.users.connect({ search: this.search });
  }

  onMention(e: SheetEventPayload) {
    console.log('mentioned', e['person']);
  }
}

A user is { id, name, email?, avatar? }, with avatar an image URL.

MemberWhat it does
wb.users.currentThe current user. With none set, it is a built-in Guest. Set it to a user object, which is added to the directory, or to the id of one already there. New comments and undo steps carry this user.
wb.users.add(...users)Adds users to the directory, so threaded comments can show and mention them.
wb.users.connect({ get, search })Connects your own store: get(id) loads one user, search(query) finds users by name or email. Both return promises.
await wb.users.get(id), await wb.users.search(text)Look users up, in the directory or your store.
wb.users.setPresence(userId, where)Publishes where a user is: { sheet, range, editing?, color? }, or null when they leave.
wb.users.editorsEveryone with published presence.

The user-changed event fires when the current user changes. before-mention (cancellable) fires before the list of people opens; cancel it and @ stays plain text.

Comments and notes

Users add notes (Shift+F2) and threaded comments (Cmd+Shift+M) with replies, mentions and a resolved state, all saved in Excel's format. From code, threads are CommentThread objects, and each comment carries the current user as its author.

JavaScript

wb.users.current = { id: 'u-17', name: 'Anna Nowak' };
const sheet = wb.sheet('Budget');

const thread = sheet.addComment('C4', 'Is this the final price?');   // starts a thread, or replies to the one there
thread.reply('Yes, agreed on Monday.');
thread.resolved = true;

for (const t of sheet.commentThreads) {
  console.log(t.address, t.resolved, t.comments.map((c) => `${c.author}: ${c.text}`));
}
sheet.commentThread('C4').edit(1, 'Yes, agreed on Monday by phone.');   // 0 is the first comment
sheet.commentThread('C4').remove();                                      // the whole thread

React

import { Sheet } from '@8sheets/react';

export function ReviewedBudget({ me, saveThread }) {
  function setUp(wb) {
    wb.users.current = me;
    wb.activeSheet.addComment('C4', 'Please check this total.');
  }

  return (
    <div style={{ height: 560 }}>
      <Sheet
        onReady={setUp}
        onCommentChanged={(e) => e.sheet.commentThreads.forEach(saveThread)}
      />
    </div>
  );
}

Vue

<script setup>
import { Sheet } from '@8sheets/vue';

const props = defineProps({ me: Object, saveThread: Function });

function setUp(wb) {
  wb.users.current = props.me;
  wb.activeSheet.addComment('C4', 'Please check this total.');
}
</script>

<template>
  <Sheet style="height: 560px" @ready="setUp" @comment-changed="(e) => e.sheet.commentThreads.forEach(props.saveThread)" />
</template>

Angular

import { Component, Input } from '@angular/core';
import { SheetComponent, SheetEventPayload, SheetsWorkbook } from '@8sheets/angular';

@Component({
  selector: 'app-reviewed-budget',
  imports: [SheetComponent],
  template: `<eight-sheet class="grid" (ready)="setUp($event)" (commentChanged)="changed($event)" />`,
  styles: `.grid { height: 560px; }`,
})
export class ReviewedBudget {
  @Input() me = { id: 'u-17', name: 'Anna Nowak' };

  setUp(wb: SheetsWorkbook) {
    wb.users.current = this.me;
    wb.activeSheet.addComment('C4', 'Please check this total.');
  }

  changed(e: SheetEventPayload) {
    for (const t of e['sheet'].commentThreads) console.log(t.address, t.comments.length);
  }
}
MemberWhat it does
sheet.addComment(cell, text)Starts a thread on a cell as the current user, or replies to the one there
sheet.commentThreads, sheet.commentThread(cell)The threads on a sheet, by row; the thread on one cell, or null
thread.commentsThe first comment and its replies, oldest first: { id, author, text, date }
thread.reply(text)Adds a reply from the current user
thread.edit(index, text)Changes a comment's text; its author and date stay, as in Excel. 0 is the first comment
thread.remove(index)Deletes a reply, or the whole thread with 0 or no index
thread.resolvedRead or set whether the thread is resolved
thread.address, thread.existsThe cell, and whether the thread is still there

Each change is one undo step and fires comment-changed; before-comment-change can cancel changes users make. A cell holds a note or a threaded comment, not both: setNote on a cell with a thread throws. Notes have their own calls (setNote, note, notes, removeNote); see Working with data.

Show where others are

Presence draws an outline with a user's name around the range they are on, as co-editing apps do. Moving presence between machines is up to your transport, such as a WebSocket you already have:

wb.users.add({ id: 'u-42', name: 'Piotr' });
wb.users.setPresence('u-42', { sheet: 'Budget', range: { r0: 4, c0: 1, r1: 4, c1: 1 }, color: '#d97706' });

// Send your own position when it changes.
wb.events.on('selection-changed', (e) => {
  socket.send(JSON.stringify({ user: wb.users.current.id, sheet: e.sheet.name, range: e.to.ranges[0] }));
});
socket.addEventListener('message', (m) => {
  const { user, sheet, range } = JSON.parse(m.data);
  wb.users.setPresence(user, { sheet, range });
});

The presence-changed event fires when someone starts or stops editing a range.

Real-time co-editing

8sheets can edit one workbook with several people at once: everyone sees the others' changes and selections as they happen, each person undoes only their own steps, and edits made while offline are sent when the connection returns. It works through a central server that orders the changes.

  • There is no hosted collaboration service for embedded workbooks yet. The server at collab.8sheets.com serves the 8sheets app only.
  • Run your own server. It comes with the source licence: tools/collab-server.mjs needs only Node and has no dependencies. The README.md of the download says how to set it up for other people: the address to listen on, a folder for the rooms, the pages allowed to connect, and a reverse proxy for TLS. It has no accounts and no rate limits, so it suits a company network or users you trust.
  • Point the workbook at it with the collabServer option. File > Share then offers your server:
const wb = await mountWorkbook(element, { collabServer: 'wss://collab.example.com/' });

A page served over HTTPS needs a wss: address, because browsers block ws: there. Add the server to connect-src if you use a Content Security Policy. With onlineFeatures: false, a server on another site is refused; one on your page's own site keeps working.

Formula results are calculated in each person's browser, so volatile functions such as RAND and NOW can show different results for different people. The Collaboration page describes sharing from the user's side: links for editing, commenting and viewing, versions and limits.