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 lets you convert React components into Qwik components, that 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:
- Don't mix React and Qwik components in the same file.
- Place all your react code inside the
src/integrations/react
folder. - Add
/** @jsxImportSource react */
at the top of the files containing React code. - 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 MUISlider = qwikify$(Slider);
import { component$ } from '@builder.io/qwik';
import { MUISlider } from '~/integrations/react/mui';
export default component$(() => {
return (
<>
<MUISlider></MUISlider>
</>
);
});
Limitations
Every qwikified react component is isolated
Each instance of a qwikified react component becomes an independent React app. Fully isolated.
export const MUISlider = qwikify$(Slider);
<MUISlider></MUISlider>
<MUISlider></MUISlider>
- Each
MUISlider
is a fully isolated React application, with its own state, lifecycle, etc. - Styles will be duplicated
- State will not be shared
- Context will not be inherited.
- Islands will hydrate independently
By default interactivity is disabled
By default, qwikified components will not be interactive, please look at the next section to learn how to enable interactivity.
qwikify$()
as a migration strategy
Use Using React components in Qwik is a great way to migrate your application to Qwik, but it's not a silver bullet, you will need to rewrite your components to take advantage of Qwik's features.
It's also a great way to enjoy the React ecosystem, like threejs or data-grid libs.
Dont abuse of
qwikify$()
to build your own application, all performance gains will be lost.
Build wide islands, not leaf nodes
For example, if you need to use several MUI components, to build a list, dont qwikify each individual MUI component, instead, build the whole list as a single qwikified React component.
GOOD: Wide island
A single qwikified component, with all the MUI components inside. Styles will not be duplicated, and context and theming will work as expected.
import * as React from 'react';
import List from '@mui/material/List';
import ListItem from '@mui/material/ListItem';
import ListItemText from '@mui/material/ListItemText';
import ListItemAvatar from '@mui/material/ListItemAvatar';
import Avatar from '@mui/material/Avatar';
import ImageIcon from '@mui/icons-material/Image';
import WorkIcon from '@mui/icons-material/Work';
import BeachAccessIcon from '@mui/icons-material/BeachAccess';
// Qwikify the whole list
export const FolderList = qwikify$(() {
return (
<List sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}>
<ListItem>
<ListItemAvatar>
<Avatar>
<ImageIcon />
</Avatar>
</ListItemAvatar>
<ListItemText primary="Photos" secondary="Jan 9, 2014" />
</ListItem>
<ListItem>
<ListItemAvatar>
<Avatar>
<WorkIcon />
</Avatar>
</ListItemAvatar>
<ListItemText primary="Work" secondary="Jan 7, 2014" />
</ListItem>
<ListItem>
<ListItemAvatar>
<Avatar>
<BeachAccessIcon />
</Avatar>
</ListItemAvatar>
<ListItemText primary="Vacation" secondary="July 20, 2014" />
</ListItem>
</List>
);
});
BAD: Leaf nodes
Leaf nodes are qwikified independently, effectively rendering dozens of nested react applications, each fully isolated from the others, and styles being duplicated.
import * as React from 'react';
import List from '@mui/material/List';
import ListItem from '@mui/material/ListItem';
import ListItemText from '@mui/material/ListItemText';
import ListItemAvatar from '@mui/material/ListItemAvatar';
import Avatar from '@mui/material/Avatar';
import ImageIcon from '@mui/icons-material/Image';
import WorkIcon from '@mui/icons-material/Work';
import BeachAccessIcon from '@mui/icons-material/BeachAccess';
export const MUIList = qwikify$(List);
export const MUIListItem = qwikify$(ListItem);
export const MUIListItemText = qwikify$(ListItemText);
export const MUIListItemAvatar = qwikify$(ListItemAvatar);
export const MUIAvatar = qwikify$(Avatar);
export const MUIImageIcon = qwikify$(ImageIcon);
export const MUIWorkIcon = qwikify$(WorkIcon);
export const MUIBeachAccessIcon = qwikify$(BeachAccessIcon);
// Qwik component using dozens of nested React islands
// Each MUI-* it's an independent React application
export const FolderList = component$(() {
return (
<MUIList sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}>
<MUIListItem>
<MUIListItemAvatar>
<MUIAvatar>
<MUIImageIcon />
</MUIAvatar>
</MUIListItemAvatar>
<MUIListItemText primary="Photos" secondary="Jan 9, 2014" />
</MUIListItem>
<MUIListItem>
<MUIListItemAvatar>
<MUIAvatar>
<MUIWorkIcon />
</MUIAvatar>
</MUIListItemAvatar>
<MUIListItemText primary="Work" secondary="Jan 7, 2014" />
</MUIListItem>
<MUIListItem>
<MUIListItemAvatar>
<MUIAvatar>
<MUIBeachAccessIcon />
</MUIAvatar>
</MUIListItemAvatar>
<MUIListItemText primary="Vacation" secondary="July 20, 2014" />
</MUIListItem>
</MUIList>
);
});
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!