API Reference

Complete reference of types, injection tokens, interfaces, and helper functions exported by the Plugin UI packages.

@gauzy/plugin-ui

Core Types

PluginUiDefinition

The main configuration object for a UI plugin.

interface PluginUiDefinition {
  id: string;
  module?: Type<any>;
  loadModule?: () => Promise<Type<any>>;
  bootstrap?: (injector: Injector) => void | Promise<void>;
  location?: string;
  plugins?: PluginUiDefinition[];
  options?: Record<string, unknown>;
  routes?: PluginRouteInput[];
  navMenu?: PluginNavContribution[];
  featureKey?: unknown;
  permissionKeys?: unknown[];
  dependsOn?: string[];
  extensions?: PageExtensionDefinition[];
  tabs?: PluginTabInput[];
  translations?: Record<string, Record<string, any>>;
  translationNamespace?: string;
  settings?: PluginSettingsSchema;
  version?: string;
  peerPlugins?: Record<string, string>;
  loadStrategy?: 'eager' | 'lazy' | 'preload';
}

PluginUiConfig

Application-level plugin configuration.

interface PluginUiConfig {
  defaultLanguage: string;
  defaultLocale: string;
  fallbackLocale?: string;
  availableLanguages: string[];
  availableLocales: string[];
  startWeekOn?: DayOfWeek;
  plugins: PluginUiDefinition[];
}

PageExtensionDefinition

Describes a UI extension contributed to an extension slot.

interface PageExtensionDefinition {
  id: string;
  slotId: string;
  component?: Type<any>;
  loadComponent?: () => Promise<Type<any>>;
  order?: number;
  title?: string;
  description?: string;
  pluginId?: string;
  hidden?: boolean;
  visible?: (context: ExtensionVisibilityContext) => boolean | Promise<boolean>;
  permissions?: string[];
  permissionsAny?: string[];
  featureKey?: string;
  wrapper?: ExtensionWrapperConfig;
  lifecycle?: ExtensionLifecycleHooks;
  metadata?: ExtensionMetadata;
}

DayOfWeek

enum DayOfWeek {
  Sunday = 0,
  Monday = 1,
  Tuesday = 2,
  Wednesday = 3,
  Thursday = 4,
  Friday = 5,
  Saturday = 6
}

PluginUiServices

Passed to PluginUiModule.init() to bridge the plugin system to the host application:

interface PluginUiServices {
  navBuilder?: Type<IDeclarativeNavBuilder>;
  routeRegistry?: Type<IDeclarativePageRouteRegistry>;
  tabRegistry?: Type<IDeclarativePageTabRegistry>;
  translateService?: Type<IPluginTranslateService>;
  permissionChecker?: Type<IPluginPermissionChecker>;
  featureChecker?: Type<IPluginFeatureChecker>;
}

All fields are optional. Values are Angular type references (classes), not instances.

Injection Tokens

Token	Type	Description
PLUGIN_UI_CONFIG	PluginUiConfig	The full plugin configuration
PLUGIN_OPTIONS	Record<string, unknown>	Per-plugin options (in plugin's child injector)
PLUGIN_DEFINITION	PluginUiDefinition	The plugin's own definition (in plugin's child injector)
PLUGIN_ACTIVATION_PREDICATE	(def: PluginUiDefinition) => boolean	Custom activation filter
PLUGIN_NAV_BUILDER	IDeclarativeNavBuilder	Navigation menu builder
PLUGIN_ROUTE_REGISTRY	IDeclarativePageRouteRegistry	Route registry
PLUGIN_TAB_REGISTRY	IDeclarativePageTabRegistry	Tab registry
PLUGIN_TRANSLATE_SERVICE	IPluginTranslateService	Translation service
PLUGIN_TRANSLATE_DELEGATE	TranslateService	Backing @ngx-translate/core service
PLUGIN_TRANSLATE_STORE_DELEGATE	TranslateStore	Backing @ngx-translate/core store
PLUGIN_APP_STORE	IPluginAppStore	Backing application store (permissions/features)
PLUGIN_PERMISSION_CHECKER	IPluginPermissionChecker	Permission checker
PLUGIN_FEATURE_CHECKER	IPluginFeatureChecker	Feature flag checker

Service Interfaces

IPluginPermissionChecker

interface IPluginPermissionChecker {
  hasAllPermissions(...permissions: string[]): boolean;
}

IPluginFeatureChecker

interface IPluginFeatureChecker {
  isFeatureEnabled(featureKey: string): boolean;
}

IPluginTranslateService

interface IPluginTranslateService {
  instant(key: string, params?: Record<string, any>): string;
  get(key: string, params?: Record<string, any>): Observable<string>;
  onLangChange: EventEmitter<{ lang: string }>;
  currentLang: string;
  setTranslation(lang: string, translations: Record<string, any>, shouldMerge?: boolean): void;
}

IDeclarativeNavBuilder

interface IDeclarativeNavBuilder {
  addNavMenuItem(item: PluginNavItemInput, sectionId?: string): void;
  removeNavMenuItem(itemId: string): void;
}

IDeclarativePageRouteRegistry

interface IDeclarativePageRouteRegistry {
  registerPageRoute(route: PluginRouteInput): void;
}

IDeclarativePageTabRegistry

interface IDeclarativePageTabRegistry {
  registerPageTab(tab: PluginTabInput): void;
}

Lifecycle Interfaces

interface IOnPluginUiBootstrap {
  ngOnPluginBootstrap(): void | Promise<void>;
}

interface IOnPluginUiDestroy {
  ngOnPluginDestroy(): void | Promise<void>;
}

interface IOnPluginAfterBootstrap {
  ngOnPluginAfterBootstrap(): void | Promise<void>;
}

interface IOnPluginBeforeDestroy {
  ngOnPluginBeforeDestroy(): void | Promise<void>;
}

interface IOnPluginBeforeRouteActivate {
  ngOnPluginBeforeRouteActivate(): boolean | Promise<boolean>;
}

interface IOnPluginConfigChange {
  ngOnPluginConfigChange(config: Record<string, unknown>): void;
}

Helper Functions

Plugin Definition

Function	Signature	Description
defineDeclarativePlugin	(id: string, config: Partial<PluginUiDefinition>) => PluginUiDefinition	Create a declarative plugin (auto-generates bootstrap callback)
definePlugin	(id: string, module: Type | LazyLoader, options?) => PluginUiDefinition	Create a module-based plugin (smart loader detection via typeof fn === 'function' && !fn.prototype)
definePluginGroup	(id: string, module: Type, options: { plugins, ... }) => PluginUiDefinition	Create a plugin group with .init() method
applyDeclarativeRegistrations	(def: PluginUiDefinition, services: { navBuilder?, pageRouteRegistry?, pageTabRegistry?, pageExtensionRegistry? }) => void	Register routes, nav, tabs, and extensions from a definition
getUIPluginModules	(defs: PluginUiDefinition[]) => Type<any>[]	Extract Angular modules from definitions
getUIPluginModulesWithDefinitions	(defs: PluginUiDefinition[]) => { module, definition }[]	Extract modules paired with definitions

Plugin Utilities

Function	Signature	Description
orderPluginsByDependencies	(defs: PluginUiDefinition[]) => PluginUiDefinition[]	Topological sort by dependencies
flattenPlugins	(defs: PluginUiDefinition[]) => PluginUiDefinition[]	Flatten nested plugin groups
collectPluginIds	(defs: PluginUiDefinition[]) => Set<string>	Collect all plugin IDs
isPluginActive	(def: PluginUiDefinition) => boolean	Check activation status
getPluginsByLocation	(defs: PluginUiDefinition[], location: string) => PluginUiDefinition[]	Filter by location
getPluginDefinition	(defs: PluginUiDefinition[], id: string) => PluginUiDefinition | undefined	Find by ID

Config Management

Function	Signature	Description
getPluginUiConfig	() => PluginUiConfig	Get current config
setPluginUiConfig	(config: PluginUiConfig) => void	Set config
resetPluginUiConfig	() => void	Reset to defaults

Dependency Validation

Function	Signature	Description
validatePluginDependencies	(defs: PluginUiDefinition[]) => ValidationResult	Validate dependency graph
logDependencyValidation	(result: ValidationResult) => void	Log validation results
checkVersionCompatibility	(defs: PluginUiDefinition[]) => CompatResult	Check peer version ranges

i18n

Function	Signature	Description
namespaceTranslations	(ns: string, translations: object) => object	Wrap translations in namespace
filterNewTranslationKeys	(existing: object, incoming: object) => object	Strip existing keys

Events

Function	Signature	Description
definePluginEvent<T>	(pluginId: string, eventName: string) => PluginEventContract<T>	Define a typed event
bindEventToBus	(contract: PluginEventContract<T>, bus: PluginEventBusService) => TypedEventHandle<T>	Bind event to bus

Services

Service	Description
PluginUiRegistryService	Central plugin registry
PageExtensionRegistryService	Extension slot registry
PluginEventBusService	Cross-plugin event bus
PluginEventSchemaRegistry	Event schema documentation
PluginSettingsRegistryService	Plugin settings storage
PluginServiceRegistryService	Cross-plugin service registry
PluginHealthService	Boot time and error monitoring
PluginDevToolsService	Debug introspection
DynamicPluginLoaderService	Runtime plugin load/unload
UiBridgeRegistryService	Framework bridge registry

Components

Component	Selector	Description
PageExtensionSlotComponent	gau-page-extension-slot	Renders extensions for a slot

Constants

Constant	Description
PAGE_EXTENSION_SLOTS	Well-known slot ID strings

---

@gauzy/ui-react

Hooks

Hook	Signature	Description
useInjector	() => Injector	Access Angular injector
useObservable	<T>(obs$: Observable<T>, initial: T) => T	Subscribe to Observable
usePluginState	<T>(pluginId, key, initial) => [T, (v: T) => void]	Shared plugin state
usePluginSettings	(pluginId: string) => Record<string, any>	All plugin settings
usePluginSetting	<T>(pluginId, key, defaultValue) => T	Single setting value
useTranslation	() => { t, currentLang }	Reactive translations
usePluginEvents	() => PluginEventBusService	Raw event bus access
usePluginEvent	(eventName: string) => { emit, on }	Basic event handle
useTypedEvent	<T>(contract) => TypedEventHandle<T>	Type-safe event handle
useTypedEventListener	<T>(contract, callback) => void	Auto-subscribed listener
useDynamicPlugin	(pluginId) => { load, unload, isLoaded }	Dynamic plugin control

Components & Directives

Export	Description
ReactHostDirective	[gaReactHost] — mount React in Angular
LazyReactHostDirective	[gaReactLazyHost] — lazy mount React in Angular
PluginErrorBoundary	React error boundary with recovery
NgContextProvider	React context providing Angular injector
NgBridgeContext	React context object
useBridgeContext	Access bridge context from React

Bridge

Export	Description
ReactBridge	Bridge class with mount/unmount
createReactBridge	Factory function
provideReactBridge	Angular provider helper
REACT_BRIDGE	Injection token

Extension Helpers

Function	Description
defineReactExtension(config)	Create eager React extension definition
defineLazyReactExtension(config)	Create lazy React extension definition
isReactExtension(ext)	Type guard for React extensions

---

@gauzy/ui-react-components

Components

Component	Props	Description
Card	CardProps (variant?: 'default' | 'accent')	Card container
CardHeader	—	Card header section
CardTitle	—	Card title text
CardDescription	—	Card description text
CardAction	—	Card action area
CardContent	—	Card body content
CardFooter	—	Card footer section
WidgetCard	Widget-specific props	Pre-styled stat card
Progress	ProgressProps (value: number)	Progress bar
ColorDots	ColorDotsProps	Color indicator dots

Design Tokens

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

theme.colors     // { primary, textPrimary, textSecondary, background, border, ... }
theme.shadows    // { card, elevated }
theme.spacing    // { xs, sm, md, lg, xl }
theme.fonts      // { family, sizeBase, sizeSmall, sizeLarge }
theme.radii      // { sm, md, lg }

Utilities

Function	Description
formatDuration(seconds: number)	Format seconds as "Xh Ym"
currentWeekRange()	Get current week start/end dates
todayRange()	Get today's start/end timestamps