yjs/renderer.md

Attribution Feature

The Attribution feature extends Yjs types to provide rich metadata about content changes, including information about who created, deleted, or formatted content. This enables powerful collaborative editing features such as authorship tracking and change visualization. The information about who performed which changes can be handled by a separate CRDT (which is part of the renderer).

Core Concepts

Renderer

A renderer renders Content (with its Attributions) to a delta. It is the central component for the attribution feature: pass it to methods like toDelta() / getDelta() to render content together with attribution metadata.

Different implementations of Renderer are available for different use cases:

• DiffRenderer: Highlights the differences between two Yjs documents
• SnapshotRenderer: Highlights the differences between two snapshots

Attributed Content

Attributed content includes standard Yjs operations enhanced with attribution metadata:

// Standard content
[{ insert: 'hello world' }]

// Attributed content
[
  { insert: 'hello', attribution: { insert: ['kevin'] } },
  { insert: ' world', attribution: { insert: ['alice'] } }
]

Delete Attribution

Deleted content is represented in attributed results to maintain authorship information and proper position tracking:

// Shows deleted content with attribution
[
  { insert: 'hello ', attribution: { delete: ['kevin'] } },
  { insert: 'world' }
]

API Reference

Y.Type

In Yjs v14 all shared types (text, array, map, xml) are instances of the unified Y.Type.

toDelta([{ renderer }])

Returns the delta representation (lib0/delta) of the type's content, optionally with attribution information.

Parameters:

• renderer (optional): The renderer instance

Returns:

• A Delta describing the content, with attribution metadata if renderer is provided

Examples:

const ytext = ydoc.get()
// Content is inserted during collaborative editing
// Attribution is handled automatically by the server

// Without attribution
const d = ytext.toDelta()
// [{ insert: 'hello world' }]

// With attribution
const attributedDelta = ytext.toDelta({ renderer })
// [
//   { insert: 'hello', attribution: { insert: ['kevin'] } },
//   { insert: ' world', attribution: { insert: ['alice'] } }
// ]

applyDelta(delta, [origin], [{ renderer }])

Applies a delta (lib0/delta) on the shared type. The optional origin is stored on the transaction (transaction.origin) and forwarded verbatim on the emitted 'delta' event (lib0 RDT spec), so listeners can recognize — and skip — changes they produced themselves. When a renderer is provided, positions in the delta are interpreted relative to the attributed (rendered) content.

Parameters:

• delta: The changes to apply
• origin (optional): Origin of the transaction that applies this delta; defaults to null
• renderer (optional): The renderer instance

YEvent

getDelta([{ renderer, deep }])

Returns the changes of an event as a delta, optionally rendered with attribution information.

Parameters:

• renderer (optional): The renderer instance
• deep (optional): Render child types as deltas

Returns:

• A Delta describing the changes, with attribution metadata if renderer is provided

Position Adjustments

When working with attributed content, position calculations must account for deleted content that appears in the attributed representation but not in the standard representation.

Example: Position Adjustment

// Standard content (length: 5)
ytext.toString() // "world"

// Attributed content (includes deleted content)
ytext.toDelta({ renderer })
// [
//   { insert: 'hello ', attribution: { delete: ['kevin'] } },  // positions 0-5
//   { insert: 'world' }                                         // positions 6-10
// ]

// To insert after "world":
// - Standard position: 5 (after "world")
// - Attributed position: 11 (after "world" accounting for deleted "hello ")

Use Cases

Events in Yjs are enhanced to work with attributed content, automatically adjusting positions when attribution is considered.

Event Position Adjustment

When a renderer is used, event positions are automatically adjusted to account for deleted content.

Example:

// Initial content: "hello world"
// User deletes "hello " (positions 0-6)
// Current visible content: "world"

ytext.observe((event, transaction) => {
  // User wants to insert "!" after "world"
  
  // Standard event (without attribution)
  const standardDelta = event.getDelta()
  // Shows insertion at position 5 (after "world" in visible content)
  
  // Attributed event (with renderer)
  const attributedDelta = event.getDelta({ renderer })
  // Shows insertion at position 11 (accounting for deleted "hello ")
  // [
  //   { insert: 'hello ', attribution: { delete: ['kevin'] } },
  //   { insert: 'world' },
  //   { insert: '!' }  // inserted at attributed position 11
  // ]
})

Use Cases

Authorship Visualization

Display content with visual indicators of who created each part:

function renderWithAuthorship(ytext, renderer) {
  const attributedDelta = ytext.toDelta({ renderer })
  
  return attributedDelta.children.map(op => {
    const author = op.attribution?.insert?.[0] || 'unknown'
    const isDeleted = op.attribution?.delete
    
    return {
      content: op.insert,
      author,
      isDeleted,
      className: `author-${author} ${isDeleted ? 'deleted' : ''}`
    }
  })
}

Change Tracking

Track who made specific changes to content:

function trackChanges(ytext, renderer) {
  ytext.observe((event, transaction) => {
    const changes = event.getDelta({ renderer })
    
    changes.children.forEach(change => {
      if (change.attribution) {
        console.log(`Change by ${change.attribution.insert?.[0] || change.attribution.delete?.[0]}:`, change)
      }
    })
  })
}

Best Practices

Renderer Lifecycle

• Create one renderer per document or collaboration session
• Ensure the renderer is consistently used across all operations
• Pass the same renderer instance to all methods that need attribution

Migration Guide

Upgrading Existing Code

To add attribution support to existing Yjs applications:

1. Add renderer: Create and configure a renderer
2. Update method calls: Add the renderer parameter to relevant method calls
3. Handle attributed content: Update code to handle the new attribution metadata format
4. Adjust position calculations: Update position calculations to account for deleted content

Backward Compatibility

The Attribution feature is fully backward compatible:

• All existing methods work without the renderer parameter
• Existing code continues to work unchanged
• Attribution is opt-in and doesn't affect performance when not used