0
# @lit/react
1
2
@lit/react provides React integration for Web Components and Reactive Controllers, enabling seamless interoperability between React applications and web components. The library offers utilities for property binding, event handling, and controller composition while maintaining type safety and following React patterns.
3
4
## Package Information
5
6
- **Package Name**: @lit/react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @lit/react`
10
11
## Core Imports
12
13
```typescript
14
import { createComponent } from "@lit/react";
15
import type { EventName, ReactWebComponent, WebComponentProps } from "@lit/react";
16
```
17
18
For the controller hook:
19
20
```typescript
21
import { useController } from "@lit/react/use-controller.js";
22
import type { ControllerConstructor } from "@lit/react/use-controller.js";
23
```
24
25
## Basic Usage
26
27
### Creating React Component Wrappers
28
29
```typescript
30
import * as React from 'react';
31
import { createComponent } from '@lit/react';
32
import { MyElement } from './my-element.js';
33
34
export const MyElementComponent = createComponent({
35
tagName: 'my-element',
36
elementClass: MyElement,
37
react: React,
38
events: {
39
onactivate: 'activate',
40
onchange: 'change',
41
},
42
});
43
44
// Usage in JSX
45
<MyElementComponent
46
active={isActive}
47
onactivate={(e) => setIsActive(e.active)}
48
/>
49
```
50
51
### Using Reactive Controllers
52
53
```typescript
54
import * as React from 'react';
55
import { useController } from '@lit/react/use-controller.js';
56
import { MouseController } from '@example/mouse-controller';
57
58
const useMouse = () => {
59
const controller = useController(React, (host) => new MouseController(host));
60
return controller.position;
61
};
62
63
const Component = () => {
64
const mousePosition = useMouse();
65
return <pre>x: {mousePosition.x} y: {mousePosition.y}</pre>;
66
};
67
```
68
69
## Architecture
70
71
@lit/react is built around two main integration patterns:
72
73
- **Component Wrapper Pattern**: `createComponent()` creates React components that properly bridge React props and web component properties/events
74
- **Controller Hook Pattern**: `useController()` adapts Lit's Reactive Controller lifecycle to React's hook system
75
- **Type Safety**: Full TypeScript integration with generic types for custom elements and events
76
- **Lifecycle Integration**: Proper integration with React's render lifecycle using `useLayoutEffect`
77
- **Server-Side Rendering**: Built-in support for SSR scenarios with `@lit/ssr-react`
78
79
## Capabilities
80
81
### Web Component Integration
82
83
Creates React component wrappers for custom elements with proper property binding and event handling, addressing React's default limitations with web components.
84
85
```typescript { .api }
86
/**
87
* Creates a React component for a custom element with proper property binding and event handling
88
* @param options Configuration object for the component wrapper
89
* @returns React ForwardRefExoticComponent that wraps the custom element
90
*/
91
function createComponent<I extends HTMLElement, E extends EventNames = {}>(
92
options: Options<I, E>
93
): ReactWebComponent<I, E>;
94
95
interface Options<I extends HTMLElement, E extends EventNames = {}> {
96
/** The React module, typically imported from the 'react' npm package */
97
react: typeof React;
98
/** The custom element tag name registered via customElements.define */
99
tagName: string;
100
/** The custom element class registered via customElements.define */
101
elementClass: Constructor<I>;
102
/** Object mapping React event prop names to custom element event names */
103
events?: E;
104
/** React component display name for debugging (defaults to element class name) */
105
displayName?: string;
106
}
107
108
type Constructor<T> = { new (): T };
109
type EventNames = Record<string, EventName | string>;
110
```
111
112
### Reactive Controller Integration
113
114
React hook that creates and manages Reactive Controllers using React's lifecycle, enabling controller composition and state management patterns from Lit in React components.
115
116
```typescript { .api }
117
/**
118
* Creates and stores a stateful ReactiveController instance with React lifecycle integration
119
* @param React The React module providing useState and useLayoutEffect hooks
120
* @param createController Function that creates a controller instance given a host
121
* @returns The created controller instance
122
*/
123
function useController<C extends ReactiveController>(
124
React: typeof window.React,
125
createController: (host: ReactiveControllerHost) => C
126
): C;
127
128
// ReactiveController and ReactiveControllerHost are imported from @lit/reactive-element
129
interface ReactiveController {
130
hostConnected?(): void;
131
hostDisconnected?(): void;
132
hostUpdate?(): void;
133
hostUpdated?(): void;
134
}
135
136
interface ReactiveControllerHost {
137
addController(controller: ReactiveController): void;
138
removeController(controller: ReactiveController): void;
139
requestUpdate(): void;
140
readonly updateComplete: Promise<boolean>;
141
}
142
143
type ControllerConstructor<C extends ReactiveController> = {
144
new (...args: Array<any>): C;
145
};
146
```
147
148
### Type System
149
150
Type utilities for enhanced TypeScript integration and type-safe event handling.
151
152
```typescript { .api }
153
/**
154
* Props type for web component used directly in React JSX
155
*/
156
type WebComponentProps<I extends HTMLElement> = React.DetailedHTMLProps<
157
React.HTMLAttributes<I>,
158
I
159
> & ElementProps<I>;
160
161
/**
162
* Type of the React component wrapping the web component (return type of createComponent)
163
*/
164
type ReactWebComponent<I extends HTMLElement, E extends EventNames = {}> =
165
React.ForwardRefExoticComponent<
166
ComponentProps<I, E> & React.RefAttributes<I>
167
>;
168
169
// Helper types used in the API
170
type ElementProps<I> = Partial<Omit<I, keyof HTMLElement>>;
171
172
type ComponentProps<I, E extends EventNames = {}> = Omit<
173
React.HTMLAttributes<I>,
174
keyof E | keyof ElementProps<I>
175
> & EventListeners<E> & ElementProps<I>;
176
177
type EventListeners<R extends EventNames> = {
178
[K in keyof R]?: R[K] extends EventName
179
? (e: R[K]['__eventType']) => void
180
: (e: Event) => void;
181
};
182
183
/**
184
* Type for casting event names with event types for better typing of event handler props
185
* @example
186
* events: {
187
* onfoo: 'foo' as EventName<FooEvent>,
188
* }
189
*/
190
type EventName<T extends Event = Event> = string & {
191
__eventType: T;
192
};
193
```
194
195
## Controller Host Implementation
196
197
The library includes a React-driven implementation of ReactiveControllerHost that bridges Lit's controller lifecycle with React hooks through an internal `ReactControllerHost` class that manages the controller lifecycle using React's `useState` and `useLayoutEffect` hooks.
198
199
## Event Handling
200
201
Enhanced event handling with type safety for custom element events.
202
203
**Basic Event Mapping:**
204
205
```typescript
206
const Component = createComponent({
207
tagName: 'my-element',
208
elementClass: MyElement,
209
react: React,
210
events: {
211
onchange: 'change',
212
oncustom: 'custom-event',
213
},
214
});
215
```
216
217
**Type-Safe Event Handling:**
218
219
```typescript
220
import type { EventName } from '@lit/react';
221
222
const Component = createComponent({
223
tagName: 'my-element',
224
elementClass: MyElement,
225
react: React,
226
events: {
227
onClick: 'pointerdown' as EventName<PointerEvent>,
228
onChange: 'input',
229
},
230
});
231
232
// Usage with properly typed event handlers
233
<Component
234
onClick={(e: PointerEvent) => console.log('Pointer event:', e)}
235
onChange={(e: Event) => console.log('Input event:', e)}
236
/>
237
```
238
239
## Server-Side Rendering
240
241
The library includes built-in support for server-side rendering when used with `@lit/ssr-react`:
242
243
```typescript
244
// SSR support is automatically enabled when litSsrReactEnabled is true
245
// or when React.createElement.name === 'litPatchedCreateElement'
246
```
247
248
## Error Handling
249
250
The library provides development-time warnings for potential integration issues:
251
252
- Warns when custom elements define properties that conflict with React reserved properties
253
- Handles property/attribute synchronization edge cases
254
- Provides proper cleanup for event listeners and controller lifecycle