1. Frameworks
2. React

Using Weavy with React

In addition to the Weavy UIKit, which is based on web components, we also offer a UIKit for React to provide an idiomatic experience for React users. Under the hood, it is powered by the Weavy UIKit for automatic access to all the latest features and updates.

Prerequisites

• A Weavy environment.
• A token endpoint in your backend that can provide an access_token for your authenticated user.
• React v16 or later.

Configure your React project

First, you need a React project to place Weavy in. If you already have a React project this step can be skipped. Otherwise we recommend following the official React installation guide as there are several great frameworks and setups to choose from when setting up a React project. Weavy supports regular React projects as well as server rendered projects (SSR), such as Next.js using React Server Components.

Install Weavy UIKit for React

Run the following command to install the Weavy UIKit for React in your project:

npm install @weavy/uikit-react

Please refer to uikit-react migration guide if you are upgrading from a previous version of Weavy UIKit for React.

Initialize the UIKit

Next you need to initialize the UIKit with some basic configuration settings. At the very least, you need to set the url to your Weavy environment and a tokenUrl or tokenFactory for authentication. Refer to the UIKit reference documentation for a full list of options.

Weavy can be configured using the <WyContext /> context provider. Set any options as attributes on the component. The <WyContext /> creates a Weavy instance and provides it to the children components. Components placed outside the provider will not access the Weavy instance.

You may alternatively import the useWeavy() hook from the @weavy/uikit-react package and pass your configuration to the hook as options. After the useWeavy hook has initialized, it returns a global Weavy instance which is accessible for all the Weavy components in the DOM. You may use the hook in several places and each config will update the global instance.

Hooks are not available server side when using Server Side Rendering (SSR) with React Server Components. To configure Weavy in server components, it's recommended to use the <WyContext /> component instead of the useWeavy() hook. Configuration for the tokenFactory can with advantage be provided using a server action which runs directly on the server.

// weavy-component.jsx
'use client'
import React from "react";
import { WyContext } from "@weavy/uikit-react";
import { tokenFactory } from "./server-actions"

export default function WeavyComponent() {
  return (
    <>
      <WyContext
        url="{WEAVY-URL}"
        tokenFactory={tokenFactory}
        >
        ...
        <SomeComponent />
      </WyContext>
    </>
  );
}

// server-actions.ts
'use server'
export async function tokenFactory(refresh) {
  return "wyu_**********";
}

import React from "react";
import { useWeavy } from "@weavy/uikit-react";
import { SomeComponent } from "./SomeComponent";

export function App() {
  const weavy = useWeavy({
    url: "{WEAVY-URL}",
    tokenUrl: "https://example.com/myapp/token",
  });

  return (
    <>
      ...
      <SomeComponent />
    </>
  );
}

Weavy components

All web components in the Weavy UIKit are available as React components but with tag names adapted to the React framework, for example <WyChat> instead of <wy-chat></wy-chat>. Property binding for attributes using prop={value} syntax may be used normally just as expected.

import React from "react";
import { WyChat } from "@weavy/uikit-react";

export function SomeComponent() {
  const chatUid = "test-chat";

  return <WyChat uid={chatUid} />;
}

Accessing Weavy in components

The created Weavy instance can be accessed from components using a context consumer. When using the <WyContext> syntax for configuration, Weavy can be accessed with the React context API by importing WeavyContext and use the standard useContext(WeavyContext) hook as long as the component is a child of the <WyContext>.

If the Weavy instance was created using the useWeavy() hook, you may alternatively create your own React context provider or use the useWeavyContext(ref) hook to access it using the Context Community Protocol. The useWeavyContext(ref) must be used with an element reference from any child from the DOM tree since it relies on standard events in the DOM.

import React, { useContext } from "react"
import { WeavyContext } from "@weavy/uikit-react"

export const MyComponent = () => {
  // Requires that weavy is configured using <WyContext> 
  const weavy = useContext(WeavyContext)

  useEffect(() => {
    if (weavy) {
      console.log("We got weavy", weavy.version)
    }
  }, [weavy])

  ...
  return (
    <></>
  )
}

import React, { useRef } from "react"
import { useWeavyContext } from "@weavy/uikit-react"

export const MyComponent = () => {
  const domRef = useRef(null)
  const weavy = useWeavyContext(domRef)

  useEffect(() => {
    if (weavy) {
      console.log("We got weavy", weavy.version)
    }
  }, [weavy])


  ...
  return (
    <>
      <span ref={domRef}></span>
      ...
    </>
  )
}

Tutorials and more

For additional info and tutorials on using Weavy with React you should also visit our technology page on React.