@uipath/apollo-react

@uipath/apollo-react

React component library with Material UI theming for the Apollo Design System.

⚠️ Important: Package Usage Guide

When to Use apollo-react

✅ Actively Supported - Use for:

• Canvas/workflow components - Hierarchical canvas, agent workflows, XYFlow integration (unique to this package)
• ApChat - AI chat interface component
• Icons - React icon components
• Core tokens - Re-exported from @uipath/apollo-core

⚠️ Maintenance Mode - Avoid for New Development:

• Material UI (./material) - Entire Material UI section including themes and Ap* components

For New Development: Use @uipath/apollo-wind

For new UI components, theming, and general application development, use @uipath/apollo-wind (Tailwind CSS + shadcn/ui) instead. It provides a modern, maintainable approach to building UI.

Note: Canvas components will remain in apollo-react but will be refactored internally to consume apollo-wind components instead of Material UI, improving maintainability while keeping the same public API.

Material UI Section (⚠️ Maintenance Mode)

The Material UI themes and components (./material) are maintained for backwards compatibility only. The themes apply Apollo design tokens to all Material UI components:

import { ThemeProvider } from '@mui/material/styles';
import { Button, TextField } from '@mui/material';
import { apolloMaterialUiThemeDark } from '@uipath/apollo-react/material/theme';

function App() {
  return (
    <ThemeProvider theme={apolloMaterialUiThemeDark}>
      <Button variant="contained">Styled with Apollo theme</Button>
      <TextField label="Uses Apollo tokens" />
    </ThemeProvider>
  );
}

Why maintenance mode?

• Moving to Tailwind CSS (apollo-wind) for better maintainability
• Material UI theming adds complexity
• Ap* components duplicate MUI's API surface

Overview

@uipath/apollo-react provides:

Actively Maintained:

• Canvas/Workflow Components - Hierarchical canvas for agent workflows with XYFlow integration
• ApChat - Full-featured AI chat interface component with i18n support
• Icons - 1300+ React icon components
• Design Tokens - Re-exported from @uipath/apollo-core

Maintenance Mode (Backwards Compatibility Only):

• Material UI (./material) - Themes and Ap* components (use @uipath/apollo-wind for new development)

Installation

npm install @uipath/apollo-react
# or
pnpm add @uipath/apollo-react
# or
yarn add @uipath/apollo-react

Note: This package is published to both npm and GitHub Package Registry. External users will automatically pull from npm. Internal UiPath users with .npmrc configured will automatically pull from GitHub Package Registry.

Quick Start

Apollo Themes with Standard Material UI

import { ThemeProvider } from '@mui/material/styles';
import { Button, TextField } from '@mui/material';
import { apolloMaterialUiThemeDark } from '@uipath/apollo-react/material/theme';

function App() {
  return (
    <ThemeProvider theme={apolloMaterialUiThemeDark}>
      <Button variant="contained">Apollo-themed Button</Button>
      <TextField label="Apollo-themed Input" />
    </ThemeProvider>
  );
}

Using Ap* Wrapper Components

import { ApButton, ApTextField } from '@uipath/apollo-react/material/components';
import { ThemeProvider } from '@mui/material/styles';
import { apolloMaterialUiThemeDark } from '@uipath/apollo-react/material/theme';

function App() {
  return (
    <ThemeProvider theme={apolloMaterialUiThemeDark}>
      <ApButton variant="primary">Click me</ApButton>
      <ApTextField label="Name" />
    </ThemeProvider>
  );
}

Package Exports

Main Entry Point

// Re-exports from material, canvas, icons, core
import { ApButton, HierarchicalCanvas } from '@uipath/apollo-react';

Material UI Components (⚠️ Maintenance Mode)

⚠️ Deprecation Notice: Ap* components are Material UI wrappers maintained for legacy support. For new projects, use @uipath/apollo-wind or standard Material UI components with Apollo themes.

// All components from single import
import { ApButton, ApTextField, ApModal } from '@uipath/apollo-react/material/components';

// Individual component imports (for smaller bundles)
import { ApButton } from '@uipath/apollo-react/material/components/ap-button';

Recommended alternative:

// Use standard MUI components with Apollo theme instead
import { Button, TextField } from '@mui/material';
import { apolloMaterialUiThemeDark } from '@uipath/apollo-react/material/theme';

Theme System

import {
  apolloMaterialUiThemeDark,
  apolloMaterialUiThemeLight,
  apolloMaterialUiThemeDarkHC,
  apolloMaterialUiThemeLightHC
} from '@uipath/apollo-react/material/theme';

Canvas Components

// Main canvas components
import {
  HierarchicalCanvas,
  AgentCanvas,
  BaseCanvas,
  BaseNode,
  GroupNode
} from '@uipath/apollo-react/canvas';

// Canvas utilities and hooks
import { useCanvasStore } from '@uipath/apollo-react/canvas/hooks';
import { Breadcrumb } from '@uipath/apollo-react/canvas/controls';

// XYFlow re-exports
import { ReactFlow, Panel } from '@uipath/apollo-react/canvas/xyflow/react';

Canvas components are styled with apollo-wind (Tailwind CSS v4). See the Canvas Tailwind Integration Guide for how to wire up the required CSS in standard and Shadow DOM apps.

ApChat Component

import { ApChat } from '@uipath/apollo-react/ap-chat';
import {
  AutopilotChatService,
  AutopilotChatMode,
  type ApChatTheme
} from '@uipath/apollo-react/ap-chat/service';

Icons

// Import specific icons
import { AddCanvas, Close, ChevronDown } from '@uipath/apollo-react/icons';

// Icon types
import type { IconName } from '@uipath/apollo-react/icons';

Design Tokens

// Re-exported from @uipath/apollo-core
import {
  ColorPrimary500,
  SpacingMd,
  FontFamilyBase
} from '@uipath/apollo-react/core';

Themes (⚠️ Maintenance Mode)

Four Material UI themes with Apollo design tokens. These themes work with all Material UI components, not just Ap* components.

Theme	Description	Import
Light	Standard light theme	apolloMaterialUiThemeLight
Dark	Standard dark theme	apolloMaterialUiThemeDark
Light High Contrast	Accessibility-focused light	apolloMaterialUiThemeLightHC
Dark High Contrast	Accessibility-focused dark	apolloMaterialUiThemeDarkHC

Theme Usage with Standard Material UI Components

The Apollo themes apply to all Material UI components, allowing you to use the standard MUI library with Apollo design tokens:

import { ThemeProvider } from '@mui/material/styles';
import { CssBaseline, Button, TextField, Card, AppBar } from '@mui/material';
import { apolloMaterialUiThemeDark } from '@uipath/apollo-react/material/theme';

function App() {
  return (
    <ThemeProvider theme={apolloMaterialUiThemeDark}>
      <CssBaseline />
      {/* Standard MUI components automatically use Apollo styling */}
      <AppBar>
        <Button variant="contained">Apollo-styled Button</Button>
        <TextField label="Apollo-styled Input" />
      </AppBar>
    </ThemeProvider>
  );
}

This approach allows you to integrate Apollo design tokens into existing Material UI applications without using Ap* wrapper components.

Icons

Access to 1300+ Apollo icons as React components:

import {
  AddCanvas,
  Close,
  ChevronDown,
  AlertError
} from '@uipath/apollo-react/icons';

function MyComponent() {
  return (
    <div>
      <AddCanvas />
      <ChevronDown />
    </div>
  );
}

Icons are auto-generated from @uipath/apollo-core with React wrappers. Icon names use PascalCase.

Internationalization (i18n)

ApChat component includes built-in i18n support for chat-related features using Lingui. The locale prop accepts supported locales:

import { ApChat } from '@uipath/apollo-react/ap-chat';
import type { SupportedLocale } from '@uipath/apollo-react/ap-chat';

// Supported locales: 'en', 'de', 'es', 'es-MX', 'fr', 'ja', 'ko', 'pt', 'pt-BR', 'ru', 'tr', 'zh-CN', 'zh-TW'
<ApChat chatServiceInstance={chatService} locale="en" />

Advanced Usage

ApChat with Service

ApChat requires setting up a service instance. See the complete documentation in the package:

import { ApChat } from '@uipath/apollo-react/ap-chat';
import {
  AutopilotChatService,
  AutopilotChatMode,
  AutopilotChatEvent
} from '@uipath/apollo-react/ap-chat/service';
import { useState, useEffect } from 'react';

function ChatInterface() {
  const [chatService, setChatService] = useState<AutopilotChatService | null>(null);

  useEffect(() => {
    // Initialize service
    const service = AutopilotChatService.Instantiate({
      instanceName: 'my-chat',
      config: {
        mode: AutopilotChatMode.SideBySide
      }
    });

    setChatService(service);

    // Subscribe to events using the AutopilotChatEvent enum
    const unsubscribeRequest = service.on(AutopilotChatEvent.Request, (data) => {
      console.log('User request:', data);
      // Handle user input
    });

    const unsubscribeFeedback = service.on(AutopilotChatEvent.Feedback, (data) => {
      console.log('User feedback:', data);
      // Handle feedback
    });

    return () => {
      unsubscribeRequest();
      unsubscribeFeedback();
      service.close();
    };
  }, []);

  if (!chatService) return null;

  return (
    <ApChat
      chatServiceInstance={chatService}
      locale="en"
      theme="light"
    />
  );
}

Note: ApChat has extensive configuration options and events. Refer to the complete API documentation for all available events, methods, and configuration options.

TypeScript Support

Full TypeScript support with exported types:

import type {
  ApButtonProps,
  ApTextFieldProps,
  AutopilotChatService,
  ApChatTheme
} from '@uipath/apollo-react';

import type { CanvasLevel } from '@uipath/apollo-react/canvas/types';

Directory Structure

apollo-react/
├── src/
│   ├── material/              # Material UI components
│   │   ├── components/        # Ap* components
│   │   └── theme/            # MUI theme overrides
│   ├── canvas/               # Canvas/workflow components
│   │   ├── components/       # Canvas components
│   │   ├── controls/         # Canvas controls
│   │   ├── hooks/           # Canvas hooks
│   │   ├── layouts/         # Layout algorithms
│   │   ├── stores/          # Zustand state stores
│   │   ├── xyflow/          # XYFlow re-exports
│   │   └── styles/          # Canvas styles
│   ├── icons/               # Icon React components
│   ├── core/                # Re-exported apollo-core
│   ├── i18n/               # Internationalization
│   └── types/              # TypeScript types
├── scripts/
│   └── icons-build.ts      # Icon generation
└── dist/                   # Built output
    ├── material/           # Material UI exports
    ├── canvas/            # Canvas exports
    ├── icons/             # Icon exports
    └── core/              # Token exports

Peer Dependencies

{
  "react": ">=18.3.0",
  "react-dom": ">=18.3.0"
}

Material UI packages and other dependencies are included.

License

MIT