Qwik React ⚛️

QwikReact allows you to use React components in Qwik, including the whole ecosystem of component libraries, such as Material UI, Threejs and React Spring.

Installation

Inside your Qwik app run:

npm run qwik add react

If you don't have a Qwik app yet, then you need to create one first, then, follow the instructions and run the command add React to your app.

npm create qwik
cd to-my-app
npm run qwik add react

Usage

The @builder.io/qwik-react package exports the qwikify$() function that allows to convert React components into Qwik components, you can use across your application.

Note: You CAN NOT use React components in Qwik without converting them first, using qwikify$(). Even though React and Qwik component look similar, they are fundamentally very different.

React and Qwik components can not be mixed in the same file, if you check your project right after running the installation command, you will see a new folder src/integrations/react/, from now on, all your React components will live there.

src/integrations/react/mui.tsx:

/** @jsxImportSource react */

import { qwikify$ } from '@builder.io/qwik-react';
import { Alert, Button, Slider } from '@mui/material';
import { DataGrid, GridColDef, GridValueGetterParams } from '@mui/x-data-grid';

export const MUIButton = qwikify$(Button);
export const MUIAlert = qwikify$(Alert);
export const MUISlider = qwikify$(Slider, { eagerness: 'hover' });

Important: You need to import /** @jsxImportSource react */ at the top of your file, this is an instruction to the compiler to use React as the JSX factory.

In a nutshell, the rules are:

1. Don't mix React and Qwik components in the same file.
2. Place all your react code inside the src/integrations/react folder.
3. Add /** @jsxImportSource react */ at the top of the files containing React code.
4. Use qwikify$() to convert React components into Qwik components, which you can import from Qwik modules.

Now your Qwik can import MUIButton and use it as any other Qwik component:

import { component$ } from '@builder.io/qwik';
import { MUIAlert, MUIButton } from '~/integrations/react/mui';

export default component$(() => {
  return (
    <>
      <MUIButton client:hover>
        Hello this is a button
      </MUIButton>

      <MUIAlert severity="warning">
        This is a warning from Qwik
      </MUIAlert>
    </>
  );
});

qwikify$()

The qwikify$(ReactCmp, options?): QwikCmp allows to implement partial hydration of React components. It works by wrapping the SSR and hydration logic of React into a Qwik component that can execute React's renderToString() during SSR and dynamically call hydrateRoot() when specified.

Notice that by default no React code will run in the browser, meaning that React component will NOT be interactive by default, for example, in the following example, we qwikify the Slider component from MUI, but it will not be interactive.

/** @jsxImportSource react */
import { qwikify$ } from '@builder.io/qwik-react';
import { Slider } from '@mui/material';
export const MUISlides = qwikify$(Button);

import { component$ } from '@builder.io/qwik';
import { MUISlider } from '~/integrations/react/mui';

export default component$(() => {
  return (
    <>
      <MUISlider></MUISlider>
    </>
  );
});

Adding interactivity

In order to add interactivity, in React terminology we need to hydrate, usually in React applications this hydration task happens unconditionally at load time, adding a massive overhead and making sites slow.

Qwik allows you decide when to hydrate your components, by using the client: JSX properties, this technique is commonly called partial hydration, popularized by Astro.

export default component$(() => {
  return (
    <>
-      <MUISlider></MUISlider>
+      <MUISlider client:visible></MUISlider>
    </>
  );
});

Qwik comes with different strategies out of the box:

client:load

The component eagerly hydrates when the document loads.

<MUISlider client:load></MUISlider>

Use case: Immediately-visible UI elements that need to be interactive as soon as possible.

client:idle

The component eagerly hydrates when the browser first become idle, ie, when everything important as already run before.

<MUISlider client:idle></MUISlider>

Use case: Lower-priority UI elements that don’t need to be immediately interactive.

client:visible

The component eagerly hydrates when it becomes visible in the viewport.

<MUISlider client:visible></MUISlider>

Use case: Low-priority UI elements that are either far down the page (“below the fold”) or so resource-intensive to load that you would prefer not to load them at all if the user never saw the element.

client:hover

The component eagerly hydrates when the mouse is over the component.

<MUISlider client:hover></MUISlider>

Use case: Lowest-priority UI elements which interactivity is not crucial, and only needs to run in desktop.

client:signal

This is an advanced API that allows to hydrate the component whenever the passed signal becomes true.

export default component$(() => {
  const hydrateReact = useSignal$(false);
  return (
    <>
      <button onClick$={() => hydrateReact.value = true}>
        Hydrate Slider when click
      </button>

      <MUISlider client:signal={hydrateReact}></MUISlider>
    </>
  );
});

This effectively allows you to implement custom strategies for hydration.

client:event

The component eagerly hydrates when specified DOM events are dispatched.

<MUISlider client:event="click"></MUISlider>

client:only

When true, the component will not run in SSR, only in the browser.

<MUISlider client:only></MUISlider>

Listening to React events

Events in React are handled by passing a function as a property to the component, for example:

// React code (won't work in Qwik)

import { Slider } from '@mui/material';

<Slider onChange={() => console.log('value changed')}></Slider>

The qwikify() function will convert this into a Qwik component that will also expose the React events as Qwik QRLs:

import { Slider } from '@mui/material';
import { qwikify$ } from '@builder.io/qwik-react';
const MUISlider = qwikify$(Slider);

<MUISlider
  client:visible
  onChange$={() => console.log('value changed')}
/>

Notice that we use the client:visible property to eagerly hydrate the component, otherwise the component would not be interactive and the events would never be dispatched.

Host element

When wrapping a React component with qwikify$(), under the hood, a new DOM element is created, such as:

<qwik-react>
  <button class="MUI-button"></button>
</qwik-react>

Notice, that the tag name of the wrapper element is configurable via tagName: qwikify$(ReactCmp, { tagName: 'my-react' }).

Listen to DOM events without hydration

The host element is not part of React, meaning that hydration is not necessary to listen for events, in order to add custom attributes and events to the host element, you can use the host: prefix in the JSX properties, such as:

<MUIButton host:onClick$={() => {
  console.log('click a react component without hydration!!');
}} />

This will effectively allow you to respond to a click in a MUI button without downloading a single byte of React code.

Happy hacking!