React

Direct support for custom elements in React has been a requested feature for long time. As you can see on Custom Elements Everywhere React scores quite low.

As of May 2024, React 19 is in beta and now better supports custom elements natively.

This means that you can use Forge components directly in React more seamlessly without any additional libraries!

The Problem

React doesn’t pass data through the JavaScript API on HTML elements. This means that any Web Components created with the Custom Elements API in the browser will suffer from the same issue when trying to pass complex data types such as array, objects, and functions through to the underlying HTML element.

Another issue is how event bubbling works in React. Since React uses its own synthetic events system, standard HTML event bubbling from custom elements doesn’t work, nor does attaching event listeners to these custom elements.

Forge + React Adapter

To make using Forge with React more seamless, we have created an adapter library that helps with the issues mentioned above.

This adapter library provides a thin wrapper component around all Forge components that allows you to pass data and listen to events in a more React-friendly way.

While the adapter is not required to use Forge with React, it is highly recommended to make the integration easier.

You can view source code for the React adapter on GitHub

Installation

To use Forge in your React application, install the following packages from npm:

npm install @tylertech/forge @tylertech/forge-react

Now that you have Forge and the React adapter installed, let’s add the rest of the setup to your React application.

Loading the Tyler Font

Edit your index.html file and add the following <link> tag to the <head> section load the Tyler font:

<link rel="stylesheet" href="https://cdn.forge.tylertech.com/v1/css/tyler-font.css" />

This will configure the default font family for your application, and load the required font weights and styles.

Importing Components

To use Forge components in your React application, import the components you need from the @tylertech/forge-react package, as well as a side-effect import from @tylertech/forge for each component to register it.

import { ForgeButton, ForgeCard } from '@tylertech/forge-react';

import '@tylertech/forge/button';
import '@tylertech/forge/card';

function App() {
  return (
    <div>
      <ForgeCard>
        <ForgeButton>Click me</ForgeButton>
      </ForgeCard>
    </div>
  );
}

Each forge-x element has a matching ForgeX wrapper (for example, forge-button becomes ForgeButton). Wrapper props use the camelCase property names, not the dash-case attribute names: labelPosition, not label-position.

Components that are only available through their own subpath import, such as forge-structured-card and forge-user-profile, have wrappers too (ForgeStructuredCard, ForgeUserProfile). They still need their side-effect import:

import { ForgeStructuredCard } from '@tylertech/forge-react';

import '@tylertech/forge/structured-card';

Importing Styles

To use the default Forge styles in your React application, import the forge.css file from the @tylertech/forge package.

import '@tylertech/forge/dist/forge.css';