@pillar-ai/react

React bindings for the Pillar Embedded Help SDK.

Installation

npm install @pillar-ai/react

Quick Start

Wrap your app with PillarProvider:

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

function App() {
  return (
    <PillarProvider helpCenter="your-help-center" publicKey="pk_live_xxx">
      <MyApp />
    </PillarProvider>
  );
}

Components

PillarProvider

The root provider that initializes the SDK and provides context to child components.

<PillarProvider
  helpCenter="your-help-center"
  publicKey="pk_live_xxx"
  config={{
    panel: { position: 'right' },
    floatingButton: { enabled: true },
    theme: { mode: 'system' },
  }}
>
  {children}
</PillarProvider>

Attach contextual tooltips to any element:

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

<Tooltip tooltipId="welcome-tooltip">
  <button>Hover me for help</button>
</Tooltip>;

PillarPanel

For custom panel placement (when using container: 'manual'):

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

function App() {
  return (
    <PillarProvider
      helpCenter="your-help-center"
      publicKey="pk_live_xxx"
      config={{ panel: { container: 'manual' } }}
    >
      <div className="layout">
        <main>Your content</main>
        <PillarPanel className="sidebar-panel" />
      </div>
    </PillarProvider>
  );
}

Hooks

usePillar

Access the SDK instance and state:

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

function MyComponent() {
  const { isReady, isOpen, pillar } = usePillar();

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

  return <div>Panel is {isOpen ? 'open' : 'closed'}</div>;
}

useHelpPanel

Control the help panel:

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

function HelpButton() {
  const { open, close, toggle, isOpen } = useHelpPanel();

  return (
    <button onClick={toggle}>{isOpen ? 'Close Help' : 'Get Help'}</button>
  );
}

Type-Safe Actions

Define custom actions with full TypeScript support:

import { PillarProvider, usePillar } from '@pillar-ai/react';
import type { ActionDefinitions } from '@pillar-ai/react';

// Define your actions
const actions = {
  openSettings: {
    type: 'navigate' as const,
    label: 'Open Settings',
    description: 'Navigate to settings page',
  },
  showNotification: {
    type: 'trigger' as const,
    label: 'Show Notification',
    description: 'Display a notification',
    dataSchema: {
      message: { type: 'string' as const, required: true },
    },
  },
} satisfies ActionDefinitions;

function App() {
  return (
    <PillarProvider
      helpCenter="your-help-center"
      publicKey="pk_live_xxx"
      actions={actions}
      onTask={(type, data) => {
        // TypeScript knows the exact shape of data based on type
        if (type === 'showNotification') {
          console.log(data.message); // Typed!
        }
      }}
    >
      <MyApp />
    </PillarProvider>
  );
}

License

MIT