ever-gauzy/packages/ui-react

@gauzy/ui-react

React-to-Angular bridge for Gauzy UI plugins. Renders React 19 components inside Angular with full access to Angular services via the dependency injection system.

Overview

This package provides the glue layer between Angular and React. It is intentionally separate from @gauzy/plugin-ui (the core plugin infrastructure) so that plugin-ui remains a pure-Angular package with no React peer dependency.

@gauzy/plugin-ui          (core, Angular-only)
       │
       └── @gauzy/ui-react   (React bridge)
                  │
                  └── @gauzy/plugin-dashboard-time-track-react-ui   (example React dashboard plugin)

Installation

yarn add @gauzy/ui-react

Peer Dependencies

• @angular/core ≥ 21
• @gauzy/plugin-ui (workspace peer)
• react ≥ 19
• react-dom ≥ 19
• rxjs ≥ 7

---

Angular Directives

ReactHostDirective

Renders a React component synchronously inside any Angular template. Selector: [gaReactHost].

<!-- host element receives the React tree -->
<div [gaReactHost]="MyReactComponent" [props]="myProps"></div>

<!-- with extra context values (a component field, see below) -->
<div [gaReactHost]="MyReactComponent" [props]="myProps" [context]="hostContext"></div>

// Both bound objects are built ONCE — never as inline literals in the template.
readonly hostContext = { theme: 'dark' };
myProps: MyProps = {};

ngOnInit(): void {
	// `@ViewChild(..., { static: true })` references exist here, not at field-initializer time.
	this.myProps = { headerActionsHost: this.headerActions.nativeElement };
}

Build the props and context objects once (e.g. as class fields or in ngOnInit), not inline in the template — the directive re-renders the React root whenever the props / context reference changes, so a fresh object literal per change-detection pass re-renders on every tick.

LazyReactHostDirective

Lazy-loads a React component via dynamic import() for code-splitting. Selector: [gaReactLazyHost].

<div [gaReactLazyHost]="loadKanban" [props]="kanbanProps"></div>

loadKanban = () => import('./kanban/KanbanBoard').then((m) => m);

---

React Hooks

useInjector()

Access Angular services from inside any React component rendered via the bridge.

import { useInjector } from '@gauzy/ui-react';
import { Router } from '@angular/router';

function MyWidget() {
	const router = useInjector(Router);

	return <button onClick={() => router.navigate(['/home'])}>Go Home</button>;
}

Without a token, returns the raw Injector:

const injector = useInjector();
const http = injector.get(HttpClient);

usePluginEvents(pluginId?)

Inter-plugin event bus from React. Subscribe and emit events across plugins.

import { usePluginEvents } from '@gauzy/ui-react';

function MyWidget() {
	const events = usePluginEvents('my-plugin');

	useEffect(() => {
		const sub = events.on('time-tracked').subscribe((event) => {
			console.log('Payload:', event.payload);
		});
		return () => sub.unsubscribe();
	}, [events]);

	return <button onClick={() => events.emit('widget-clicked', { id: 1 })}>Click</button>;
}

usePluginEvent(type, callback, options?, deps?)

Single-event subscription with automatic cleanup on unmount.

import { usePluginEvent } from '@gauzy/ui-react';

function MyWidget() {
	usePluginEvent('time-tracked', (event) => {
		console.log('Time tracked:', event.payload);
	});

	return <div>Listening...</div>;
}

useBridgeContext()

Access the full bridge context (injector + any extra values passed via the context input).

import { useBridgeContext } from '@gauzy/ui-react';

function MyWidget() {
	const { injector, theme } = useBridgeContext();
	return <div style={{ color: theme as string }}>Hello</div>;
}

---

React Bridge API

ReactBridge

Low-level class implementing UiBridge from @gauzy/plugin-ui. Use it when you need direct control over mounting/unmounting.

import { ReactBridge } from '@gauzy/ui-react';

const bridge = new ReactBridge();

const result = bridge.mount({
	component: MyReactComponent,
	props: { title: 'Hello' },
	hostElement: document.getElementById('host')!,
	injector: angularInjector
});

// Later:
result.unmount();
// Or update props:
result.updateProps?.({ title: 'Updated' });

provideReactBridge()

Environment provider — registers ReactBridge in Angular DI.

import { provideReactBridge, REACT_BRIDGE } from '@gauzy/ui-react';

// In app.config.ts or AppModule providers:
provideReactBridge();

// Then inject anywhere:
const bridge = inject(REACT_BRIDGE);

---

Defining React Extensions

Use defineReactExtension() to register a React component as a plugin extension slot contribution.

import { defineReactExtension } from '@gauzy/ui-react';
import { MyWidget } from './MyWidget';

export const myExtension = defineReactExtension({
	id: 'my-widget',
	slotId: 'dashboard-widgets',
	component: MyWidget,
	props: { title: 'My Widget' },
	order: 10
});

Then add it to a plugin definition:

import { defineDeclarativePlugin } from '@gauzy/plugin-ui';

export const MyPlugin = defineDeclarativePlugin('my-plugin', {
	extensions: [myExtension]
});

---

Building

yarn nx build ui-react
yarn nx build ui-react --configuration=production

Testing

yarn nx test ui-react