# Real-time collaboration

Collaboration shares edits, cursors, and presence among users in the same room. A room name alone does not automatically connect devices over the internet.

Canonical: https://grid.syidax.com/docs/features/collaboration/

<a id="understand"></a>

## How it works and when to use it

Without realtimeUrl, the feature serves demos within the same process or page. Multi-user deployments need an app-provided WebSocket service, authentication, room permissions, and persistence policy.

Using this feature in a product requires the Pro package and a valid license. Matching setting names do not enable Pro features in Community.

In the code, grid is the Grid element prepared in the installation chapter. Check each example's data and settings, and implement the app functions and server endpoints for your project.

- [Installation and integration · Shared sample data](https://grid.syidax.com/docs/guides/getting-started.md)

<a id="example-1"></a>

## Example 1. Test connections on the same page

Give two Grids the same room name and matching data-ID rules.

```javascript
grid.collaborationRoom = 'orders-review';
grid.collabUserName = 'Reviewer A';
grid.collabUserColor = '#2459d3';
```

Verify the result: Check edit synchronization with another participant on the same page. Do not describe this as a connection to a real remote service.

<a id="example-2"></a>

## Example 2. Connect remote collaboration

Set realtimeUrl to the app's authenticated WebSocket endpoint and implement joining and leaving. Enforce room permissions on the server so users cannot read other rooms' data.

Verify the result: Use syncStatusChanged to communicate disconnection and reconnection, and distinguish persistent saving from message delivery.

<a id="example-3"></a>

## Example 3. Read synchronization results

Connect remote edits and conflict-resolution results to the app's activity history.

```javascript
grid.addEventListener('remoteEditApplied', event => console.log(event.detail));
grid.addEventListener('collabConflictResolved', event => console.log(event.detail));
```

Verify the result: Inspect actual detail when users edit the same cell concurrently. Track the change source to avoid retransmission loops.

<a id="pitfalls"></a>

## Combining features and troubleshooting

All participants must use the same rowId and column-identifier rules. Do not associate remote edits with display indices.

Collaboration status does not confirm persistent storage or audit retention. Connect persistence policy to the app server.

<a id="related-api"></a>

## APIs used by this feature

- [collaborationRoom](https://grid.syidax.com/docs/options/collaborationRoom.md) — Collaboration room ID for sharing edits and presence. Connecting multiple devices requires remote service configuration.
- [realtimeUrl](https://grid.syidax.com/docs/options/realtimeUrl.md) — WebSocket URL for remote collaboration. When omitted, collaboration is limited to a same-page/process demo scope.
- [collabUserName](https://grid.syidax.com/docs/options/collabUserName.md) — User name shown to other collaboration participants.
- [collabUserColor](https://grid.syidax.com/docs/options/collabUserColor.md) — Distinctive color for the participant's cursor and presence indicators.
- [collabPresence](https://grid.syidax.com/docs/options/collabPresence.md) — Configures participant position and presence indicators.
- [collabConflictUi](https://grid.syidax.com/docs/options/collabConflictUi.md) — Configures user-facing conflict guidance for concurrent edits.
- [collabPersistence](https://grid.syidax.com/docs/options/collabPersistence.md) — Disables local collaboration persistence or uses IndexedDB. Does not replace server backups.
- [connectCollabRoom](https://grid.syidax.com/docs/methods/connectCollabRoom.md) — Starts the configured collaboration room connection and returns synchronization state.
- [disconnectCollabRoom](https://grid.syidax.com/docs/methods/disconnectCollabRoom.md) — Disconnects from the current collaboration room.
- [getSyncStatus](https://grid.syidax.com/docs/methods/getSyncStatus.md) — Reads current collaboration connection and synchronization state.
- [getCollaborators](https://grid.syidax.com/docs/methods/getCollaborators.md) — Reads current collaboration participant information.
- [remoteEditApplied](https://grid.syidax.com/docs/events/remoteEditApplied.md) — Emitted when a collaborator's edit is applied. Track its origin to avoid resending it as a local edit and creating a loop.
- [presenceChanged](https://grid.syidax.com/docs/events/presenceChanged.md) — Emitted when participant positions or presence change.
- [collabConflictResolved](https://grid.syidax.com/docs/events/collabConflictResolved.md) — Emitted when a concurrent editing conflict is resolved. Read the actual outcome before explaining it to users.
- [collaboratorJoined](https://grid.syidax.com/docs/events/collaboratorJoined.md) — Emitted when a participant joins the collaboration room.
- [collaboratorLeft](https://grid.syidax.com/docs/events/collaboratorLeft.md) — Emitted when a participant leaves. Update the app's participant list by ID.
- [syncStatusChanged](https://grid.syidax.com/docs/events/syncStatusChanged.md) — Emitted when collaboration synchronization changes. Distinguish connection state from completed persistent server saving.

<a id="next"></a>

## Related reading

- [How rows, columns, and IDs relate](https://grid.syidax.com/docs/guides/concepts.md)
- [Connect results and events](https://grid.syidax.com/docs/guides/data-event-access.md)
- [Explore in Features](https://grid.syidax.com/grid/collaboration) — The guide describes which interactions are available to try.