Jazz UI Development

When to Use This Skill

• Building user interfaces that display or interact with Jazz data
• Setting up authentication providers and contexts
• Debugging reactivity, data loading, or sync issues in the UI
• Optimizing performance of data subscriptions
• Handling media (images, files) in the UI

Do NOT Use This Skill For

• Defining data schemas (use

  jazz-schema-design

  )
• Complex permission logic or sharing workflows (use

  jazz-permissions-security

  )
• Testing questions (use

  jazz-testing

  )

Key Heuristic for Agents

Framework Guides

• React: React Reference
• React Native (Bare): As well as the React guide, also see React Native Reference
• React Native (Expo): As well as the React guide, also seeReact Native (Expo) Reference
• Svelte: Svelte Reference
• Vanilla JS: Vanilla JS Reference

Universal CoValue API

Core Properties

• $isLoaded

  (

  boolean

  ): Returns

  true

  if the CoValue is fully loaded and ready to read.

• .toJSON()

  : Returns a plain JavaScript object representation of the CoValue. Use this for debugging only, not for rendering.

The

.$jazz

Namespace

.$jazz

Metadata

• .$jazz.id

  (

  ID<CoValue>

  ): The globally unique ID of the CoValue (e.g.,

  co_zXy...

  ).

• .$jazz.owner

  (

  Group

  ): The Group that owns this CoValue. Access control is determined by membership in this group.

• .$jazz.createdAt

  (

  number

  ): Creation timestamp (ms since epoch).

• .$jazz.createdBy

  (

  ID<Account> | undefined

  ): ID of the creating account.

• .$jazz.lastUpdatedAt

  (

  number

  ): Last update timestamp (ms since epoch).

Loading & Inspection

• .$jazz.loadingState

  (

  "loading" | "loaded" | "unavailable" | "unauthorized"

  ): The current loading state.

• .$jazz.ensureLoaded({ resolve: { ... } })

  : Waits for nested references to load. Returns a promise with a new instance where requested fields are guaranteed available.

const detailedPost = await post.$jazz.ensureLoaded({
  resolve: {
    comments: {
      $each: {
        author: true 
      }
    }
  }
});

• .$jazz.refs

  (CoMap/CoRecord only): Access nested CoValues as references (with IDs) without loading them.

• .$jazz.has(key)

  (CoMap/CoRecord only): Checks if a key exists.

Subscription & Sync

• .$jazz.subscribe(callback)

  : Manually subscribe to changes. Returns an unsubscribe function. Prefer framework-specific hooks (e.g.,

  useCoState

  ) over this.

• .$jazz.waitForSync()

  : Promise that resolves when changes are synced to peers. Useful for critical saves or logout flows.

Version Control

• .$jazz.isBranched

  (

  boolean

  ): Whether the CoValue is currently in a local branch.

• .$jazz.branchName

  (

  string

  ): The name of the current branch.

• .$jazz.unstable_merge()

  : Merges a branch back into the main history.

Working with Data Types

CoMap / CoRecord

• Read: Access properties like a standard JS object (e.g.,

  user.name

  ).
• Write:

  • .$jazz.set(key, value)

  • .$jazz.delete(key)

  • .$jazz.applyDiff(diff)

CoList

• Read: Access by index (

  list[0]

  ), iterate (

  map

  ,

  forEach

  ).
• Write:

  • .$jazz.push(item)

  • .$jazz.unshift(item)

  • .$jazz.splice(...)

  • .$jazz.remove(index or predicate)

CoText (CoPlainText / CoRichText)

• Read:

  toString()

  or use directly in template.
• Write:

  • insertAfter(index, text)

  • deleteRange({ from, to })

  • .$jazz.applyDiff(newText)

CoFeed

• Read: Iterate over

  feed.all

  (returns per-session feeds).
• Write:

  .$jazz.push(item)

  (Append-only).

// Subscribing to all entries across all accounts
const allEntries = Object.values(feed.perAccount).flatMap(accountFeed => Array.from(accountFeed.all));

// Pushing a new entry
feed.$jazz.push({ message: "Hello", timestamp: Date.now() });

DiscriminatedUnion

• Read: Check the discriminator property (e.g.

  type

  ) to narrow the type.
• Write: Overwrite the property with a new object of the desired variant.

const list = co.list(MyUnion);
const item = list[0];

if (item.type === "text") {
  console.log(item.value); // item is narrowed to TextVariant
} else if (item.type === "image") {
  console.log(item.image.$jazz.id); // item is narrowed to ImageVariant
}

FileStream

• Read: Use

  toBlob()

  or consume chunks.
• Write: Use

  createFromBlob(blobOrFile)

  or

  start(metadata) -> push(chunk) -> end()

  .

ImageDefinition

• Read: Use

  <Image>

  component (framework specific) or

  loadImageBySize

  .
• Write: use the

  createImage

  function from

  jazz-tools/media

<Image imageId={productImage.$jazz.id} width={300} />

Troubleshooting

"Data not appearing" or "Value is undefined"

1. Check

   $isLoaded

   : Ensure you are checking

   if (coValue.$isLoaded)

   before rendering.
2. Deep Loading: If nested data is missing, use

   resolve

   in your hook (e.g.

   useCoState(..., { resolve: { items: true } })

   ).
3. Provider Check: Ensure the component is wrapped in the appropriate

   <JazzProvider />

   .

"Infinite re-render loops"

1. Selector Stability: Ensure your

   select

   function in

   useCoState

   is stable or returns stable references.
2. Expensive Selectors: Move computations to

   useMemo

   instead of doing them inside the

   select

   function.
3. Equality Function: Use

   equalityFn

   to prevent unnecessary updates if the selected data hasn't changed semantically.

"Reactivity not triggering"

1. Direct Mutations: Ensure you are using

   .$jazz.set()

   or

   .$jazz.push()

   instead of direct property assignment (e.g.

   obj.key = val

   won't sync).
2. Deep Updates: Remember that updating a nested scalar doesn't trigger a change in the parent CoValue unless that parent property is replaced.