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

Use this skill when the user asks about rendering data, handling user input, managing authentication state, or framework-specific integration (React, Svelte, etc.). If the issue is "data not appearing" but permissions are correct, look here for loading and subscription patterns.

Framework Guides

Select the guide for your specific framework:

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

These APIs are available on all CoValue instances, regardless of the framework.

Core Properties

All CoValues (CoMaps, CoLists, etc.) have these properties directly on the instance:

```
$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

Every CoValue instance has a

.$jazz

property containing metadata and utility methods.

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)

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

ImageDefinition

Read: Use
```
<Image>
```
component (framework specific) or
```
loadImageBySize
```
.
Write: use the
```
createImage
```
function from
```
jazz-tools/media
```

tsx

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

Troubleshooting

"Data not appearing" or "Value is undefined"

Check
$isLoaded
: Ensure you are checking
```
if (coValue.$isLoaded)
```
before rendering.
Deep Loading: If nested data is missing, use
```
resolve
```
in your hook (e.g.
```
useCoState(..., { resolve: { items: true } })
```
).
Provider Check: Ensure the component is wrapped in the appropriate
```
<JazzProvider />
```
.

"Infinite re-render loops"

Selector Stability: Ensure your
```
select
```
function in
```
useCoState
```
is stable or returns stable references.
Expensive Selectors: Move computations to
```
useMemo
```
instead of doing them inside the
```
select
```
function.
Equality Function: Use
```
equalityFn
```
to prevent unnecessary updates if the selected data hasn't changed semantically.

"Reactivity not triggering"

Direct Mutations: Ensure you are using
```
.$jazz.set()
```
or
```
.$jazz.push()
```
instead of direct property assignment (e.g.
```
obj.key = val
```
won't sync).
Deep Updates: Remember that updating a nested scalar doesn't trigger a change in the parent CoValue unless that parent property is replaced.

jazz-ui-development

NPX Install

Tags

SKILL.md Content

Jazz UI Development

When to Use This Skill

Do NOT Use This Skill For

Key Heuristic for Agents

Framework Guides

Universal CoValue API

Core Properties

The
`.$jazz`
Namespace

Metadata

Loading & Inspection

Subscription & Sync

Version Control

Working with Data Types

CoMap / CoRecord

CoList

CoText (CoPlainText / CoRichText)

CoFeed

DiscriminatedUnion

FileStream

ImageDefinition

Troubleshooting

"Data not appearing" or "Value is undefined"

"Infinite re-render loops"

"Reactivity not triggering"