DocsConceptsAttached vs Detached States

Attached vs Detached States

Quick Reference

Loro uses “attached/detached” in two distinct contexts:

  1. Document States - Version synchronization (latest vs historical)
  2. Container States - Document membership (belongs to doc vs standalone)

⚠️ These are independent concepts - a container can be attached to a detached document.

Document States

Attached (Default)

  • Synchronized with latest OpLog version
  • Normal editing mode
  • All operations applied immediately
const  = new ();
.(.()); // false - normal state

Detached (Time Travel)

  • Viewing historical version
  • Editing disabled by default
  • OpLog has newer operations not shown
const  = new ();
.("text").(0, "v1");
const  = .();
.("text").(2, " -> v2");
 
// Time travel to v1
.();
.(.()); // true
.(.("text").()); // "v1"

Container States

Detached (Standalone)

  • Created with constructors (new LoroMap())
  • Not part of any document
  • No valid ContainerID
  • Used as templates
const  = new ();
.(.()); // false

Attached (Document Member)

  • Part of document hierarchy
  • Has ContainerID
  • Changes tracked in document
const  = new ();
const  = .("data"); // Attached
 
// Adding detached container returns attached version
const  = new ();
const  = .("text", );
.(.()); // false - original unchanged
.(.()); // true - new attached copy

Key Differences

AspectDocument Attached/DetachedContainer Attached/Detached
PurposeVersion controlDocument membership
WhenTime travel, branchingAdding to document
IndependenceN/AIndependent from doc state
EditingRestricted when detachedAlways allowed

Common Use Cases

Time Travel

const  = new ();
const  = .();
// ... more edits ...
.(); // View old version
.(); // Return to latest

Container Templates

const  = new ();
.("type", "task");
 
const  = new ();
const  = .("tasks");
// Reuse template multiple times
.(0, );
.(1, );

Related Documentation

ContainerOpLog and DocState Separation