- Spreadsheet docs
- 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.
| Member | What it does |
|---|---|
wb.users.current | The 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.editors | Everyone 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 threadReact
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);
}
}| Member | What 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.comments | The 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.resolved | Read or set whether the thread is resolved |
thread.address, thread.exists | The 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.mjsneeds only Node and has no dependencies. TheREADME.mdof 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
collabServeroption. 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.