@y-sweet/react

React library for building collaboration features with y-sweet.

Installation

npm install @y-sweet/react
Copy

Documentation

Read the documentation for guides and API references.

Examples

Explore our collaborative examples to help you get started.

All examples are open source and live in this repository, within /examples.

Using @y-sweet/react

useMap is a shared object or map

useMap exposes a Yjs Y.Map. You can refer to the documentation for Y.Map here.

Our Color Grid example uses useMap to store a grid of colors using coordinates as keys.

const items = useMap<string>('colorgrid')

items.delete(key)
items.set(`${x},${y}`, color)
Copy

useArray is a shared array

useArray exposes a Yjs Y.Array. You can refer to the documentation for Y.Array here.

Our To Do List example, which uses useArray to store a list of To Do items.

The To Do List stores an array of objects of type Y.Map (a Yjs type). This maintains the order of the To Do List, while being able to indicate whether an item is ‘done’.

const items = useArray<Y.Map<any>>('todolist')

const pushItem = useCallback((text: string) => {
    let item = new Y.Map([
        ['text', text],
        ['done', false],
    ] as [string, any][])

    items?.push([item])
},[items])

const clearCompleted = useCallback(() => {
    let indexOffset = 0
    items?.forEach((item, index) => {
        if (item.get('done')) {
            items.delete(index - indexOffset, 1)
            indexOffset += 1
        }
    })
}, [items])
Copy

useText is a shared string

useText exposes a Yjs Y.Text. You can refer to the documentation for Y.Text here.

Our Text Editor example, which uses useText to store the text document.

const yText = useText('text')
Copy

Add presence features

useAwareness returns an Yjs awareness object

The awareness object can be applied to editor bindings with Yjs that have built in presence features.

Our Code Editor demo passes the awareness object to the CodeMirror Yjs binding.

const awareness = useAwareness()

bindingRef.current = new CodemirrorBinding(yText!, editorRef.current, awareness)
Copy

usePresence for general purpose presence features

The usePresence hook is a more opinionated service that lets you define what presence data you're saving.

This is easier for building your own live cursors or avatars than the using the useAwareness hook.

Our Presence demo defines presence as a map of x,y keys and color value pairs.

const [presence, setPresence] = usePresence<{ x: number; y: number; color: string }>()

const updatePresence = useCallback((e: React.MouseEvent<HTMLDivElement>) => {
setPresence({
    x: e.clientX - e.currentTarget.offsetLeft,
    y: e.clientY - e.currentTarget.offsetTop,
    color: myColor.current,
})
}, [setPresence])

<div
    className="border-blue-400 border relative overflow-hidden w-[500px] h-[500px]"
    onMouseMove={updatePresence}
>
    {Array.from(presence.entries()).map(([key, value]) => (
        <div
            key={key}
            className={`absolute rounded-full ${value.color}`}
            style={{ left: value.x - 6, top: value.y - 8, width: 10, height: 10 }}
        />
    ))}
</div>
Copy