React Component Wrappers

Updated:
This feature is experimental within the Stencil Library (Docs) and is automated within their build process. Please report any issues encountered. However, note that the Tecton team does not maintain this specific tool.

This tutorial assumes your codebase is registering the Web Components via connect from the q2-tecton-sdk, or from the q2-design-system library.

If you're using React to build out your feature or application, then you can make use of the React component wrappers that are published as a part of Tecton.

This gives you a number of benefits including:

  • Direct event handling with tct-prefixed events (e.g., onTctChange, onTctInput)
  • Autocompletion and type safety
  • Simplified code without refs or workarounds for most use cases

Getting started

Making use of the React component wrappers only requires a couple of steps.

First, you will need to install the framework wrappers library:

  • NPM: npm i q2-tecton-framework-wrappers
  • Yarn: yarn add q2-tecton-framework-wrappers
  • Pnpm: pnpm add q2-tecton-framework-wrappers

Using the components

Once the package is installed you can start using the components by importing the ones you need, just like you would with any other components. They are all located in q2-tecton-framework-wrappers/dist/react.

import { Q2Btn, Q2Input, Q2Section } from "q2-tecton-framework-wrappers/dist/react";

function Example() {
  const handleInput = (event: CustomEvent) => {
    console.log(event.detail.value);
  };

  return (
    <Q2Section label="My Section" collapsible expanded>
      <Q2Input label="Full name" optional onTctInput={handleInput} />
      <Q2Btn intent="workflow-primary">Submit</Q2Btn>
    </Q2Section>
  );
}

Working with events

Starting with Tecton v1.65.0, all Tecton Web Component events are prefixed with tct (e.g., tctChange, tctInput, tctPopoverStateChanged). Since these don't conflict with React's synthetic event system, you can use standard React event handler syntax directly:

<Q2Input
  label="Name"
  onTctInput={(event: CustomEvent) => {
    console.log(event.detail.value);
  }}
  onTctChange={(event: CustomEvent) => {
    console.log("Changed:", event.detail.value);
  }}
/>

This is the recommended approach for all Tecton events.

Using refs for non-tct events

If you need to listen to events that are not prefixed with tct (e.g., you're on a version of Tecton before v1.65.0), or if you encounter conflicts with React's synthetic event system (e.g., native input or change events), you can use refs as a fallback.

This approach involves:

  1. Creating a ref with useRef
  2. Adding event listeners in a useEffect hook
  3. Cleaning up listeners when the component unmounts

Example:

import { Q2Input } from "q2-tecton-framework-wrappers/dist/react";
import { useEffect, useRef } from "react";

function MyComponent() {
  const inputRef = useRef<HTMLQ2InputElement>(null);

  useEffect(() => {
    const input = inputRef.current!;
    const onInput = (event: Event) => {
      const newEvent = event as CustomEvent;
      console.log("onInput", newEvent.detail);
    };

    input.addEventListener("input", onInput);

    return () => {
      input.removeEventListener("input", onInput);
    };
  }, []);

  return <Q2Input ref={inputRef} label="Name" />;
}