React API Reference

import { PillarProvider } from '@pillar-ai/react';

<PillarProvider
  productKey="your-product-key"
  publicKey="pk_live_xxx"
  config={{
    panel: { position: 'right', mode: 'push', width: 400 },
    theme: { mode: 'auto', colors: { primary: '#2563eb' } },
  }}
  onTask={(task) => { /* handle tasks */ }}
  cards={{ invite_members: InviteMembersCard }}
>
  {children} {/* Your app content */}
</PillarProvider>

import { usePillar } from '@pillar-ai/react';

function MyComponent() {
  const {
    pillar,      // SDK instance
    isReady,     // Whether SDK is initialized
    isPanelOpen, // Panel open state
    open,        // Open the panel
    close,       // Close the panel
    toggle,      // Toggle the panel
    navigate,    // Navigate to a view
    setTheme,    // Update theme at runtime
    on,          // Subscribe to events
    onTask,      // Register task handler
    activePlan,  // Current active plan
  } = usePillar();

  if (!isReady) {
    return <div>Loading...</div>;
  }

  return (
    <button onClick={() => open()}>
      Get Help
    </button>
  );
}

// Open to home view
open();

// Open to a specific article
open({ article: 'getting-started' });

// Open with a search query
open({ search: 'billing' });

// Open and focus the input
open({ focusInput: true });

// Open to the chat view
open({ view: 'chat' });

import { usePillar } from '@pillar-ai/react';
import type { actions } from '@/lib/pillar/actions';

function TaskHandlers() {
  const { onTask } = usePillar<typeof actions>();

  useEffect(() => {
    // TypeScript knows the exact data shape for each action
    const unsub = onTask('add_source', (data) => {
      console.log(data.url); // Typed as string
      return { success: true };
    });

    return unsub;
  }, [onTask]);

  return null;
}

import { useHelpPanel } from '@pillar-ai/react';

function HelpButton() {
  const {
    isOpen,
    open,
    close,
    toggle,
    openArticle,
    openCategory,
    openSearch,
    openChat,
  } = useHelpPanel();

  return (
    <div>
      <button onClick={toggle}>
        {isOpen ? 'Close' : 'Help'}
      </button>
      <button onClick={() => openArticle('getting-started')}>
        Getting Started
      </button>
      <button onClick={openChat}>
        Ask co-pilot
      </button>
    </div>
  );
}

import { PillarProvider, PillarPanel } from '@pillar-ai/react';

function App() {
  return (
    <PillarProvider
      productKey="your-product-key"
      publicKey="pk_live_xxx"
      config={{
        panel: { enabled: false }, // Disable auto-rendering
      }}
    >
      <div className="app-layout">
        <main>Your app content</main>
        
        {/* Render panel in a custom location */}
        <aside className="help-sidebar">
          <PillarPanel className="custom-panel" />
        </aside>
      </div>
    </PillarProvider>
  );
}

interface CardComponentProps<T = Record<string, unknown>> {
  /** Data extracted by the AI */
  data: T;
  
  /** Call when user confirms the action */
  onConfirm: (modifiedData?: Record<string, unknown>) => void;
  
  /** Call when user cancels */
  onCancel: () => void;
  
  /** Report state changes */
  onStateChange?: (state: 'loading' | 'success' | 'error', message?: string) => void;
}

import type { CardComponentProps } from '@pillar-ai/react';

interface InviteData {
  emails: string[];
  role: 'admin' | 'member';
}

export function InviteMembersCard({ data, onConfirm, onCancel }: CardComponentProps<InviteData>) {
  return (
    <div>
      <p>Invite {data.emails.length} members as {data.role}</p>
      <button onClick={onCancel}>Cancel</button>
      <button onClick={() => onConfirm(data)}>Confirm</button>
    </div>
  );
}

interface PillarConfig {
  /** Panel configuration */
  panel?: {
    enabled?: boolean;
    position?: 'left' | 'right';
    mode?: 'overlay' | 'push';
    width?: number;
    container?: string | HTMLElement;
  };

  /** Edge trigger configuration */
  edgeTrigger?: {
    enabled?: boolean;
    position?: 'left' | 'right';
    label?: string;
  };

  /** Text selection popover */
  textSelection?: {
    enabled?: boolean;
    label?: string;
  };

  /** Theme configuration */
  theme?: ThemeConfig;

  /** Custom CSS to inject */
  customCSS?: string;
}

interface ThemeColors {
  /** Brand color for buttons, links, accents */
  primary?: string;
  
  /** Hover state for primary color */
  primaryHover?: string;
  
  /** Main background color */
  background?: string;
  
  /** Secondary background (cards, inputs) */
  backgroundSecondary?: string;
  
  /** Primary text color */
  text?: string;
  
  /** Secondary/muted text color */
  textMuted?: string;
  
  /** Border color */
  border?: string;
  
  /** Subtle border color */
  borderLight?: string;
}

interface Task {
  /** Unique identifier for this task execution */
  id: string;
  
  /** The action name that triggered this task */
  name: string;
  
  /** Data extracted by the AI, matching the action's dataSchema */
  data: Record<string, unknown>;
  
  /** Complete the task and report the result */
  complete: (result: TaskResult) => void;
}

interface TaskResult {
  /** Whether the task completed successfully */
  success: boolean;
  
  /** Optional message to display to the user */
  message?: string;
}