Using Weavy with React

We offer an UIKit for React with versions of all our building blocks to provide an idiomatic experience for React users. Under the hood, it is powered by UIKit Web for automatic access to all the latest features and updates.

Prerequisites

  • A Weavy environment.
  • An endpoint in your backend that can provide a JSON response with an access_token for your authenticated user.
  • React v16 or later.

Configure your React project

First of all you should setup a React project. If you already have a project configured with React you can skip this step. 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.

Install UIKit React

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

Weavy comes with a dedicated UIKit for React that has regular React components together with some additional React hooks for easy configuration and usage. The React components are based on UIKit Web and can leverage all the functionality found there.

npm install @weavy/uikit-react

Configure Weavy using a hook

Similar to UIKit Web, you need to configure Weavy with the url to your environment and a tokenUrl or tokenFactory to configure authentication. All other configuration options in UIKit Web are also available in UIKit React.

Weavy can be configured inside React components by using a hook. Simply 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 the Weavy instance.

We recommend placing a single hook in a component at the highest level possible in the render-tree. Having the hook in multiple places may cause unexpected configuration behavior.

You may alternatively use the <WyContext /> component with configuration properties in JSX instead of using the useWeavy hook.

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

export function App() {
  const weavy = useWeavy({
    url: "https://myenvironment.weavy.io",
    tokenUrl: "https://myserver.test/api/token",
  });

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

Pitfall: Avoid using new URL(...) in your options as React then creates a new URL on each render, causing Weavy to be reconfigured on each render.

Using Weavy React components

All components in UIKit Web are also available in UIKit React as regular React components but with tag names adapted to the React framework, for example <WyChat> and <WyMessenger>. Property binding for attributes in React using prop={value} syntax may be used normally as expected.

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

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

  return <WyChat uid={chatUid} />;
}
Block React component Web Component (uikit-web)
Weavy <WyContext /> <wy-context><wy-context>
Chat <WyChat /> <wy-chat></wy-chat>
Files <WyFiles /> <wy-files></wy-files>
Messenger <WyMessenger /> <wy-messenger></wy-messenger>
Posts <WyPosts /> <wy-posts></wy-posts>

Using events on the Weavy blocks

All events are available with property binding using the regular React event naming standard onEventName. That means the Chat event "wy:message-created" is available using onWyMessageCreated.

<WyChat onWyMessageCreated={(e) => console.log(e.detail)} />

For a list of events available on each components see the UIKit Web reference.

Weavy Docs