Search documentation

Search documentation

Core SDK@pillar-ai/sdk

Cards

Register custom card renderers for inline UI.

typescript
import Pillar from '@pillar-ai/sdk'

Methods

Pillar.registerCard()

Register a custom card renderer for inline_ui type actions. When the AI returns an action with action_type: 'inline_ui' and a card_type in its data, the SDK will look for a registered renderer and call it to render the inline UI card.

typescript
registerCard(cardType: string, renderer: CardRenderer): () => void

Parameters

cardType
requiredstring
- The card type identifier (e.g., 'invite_members')
renderer
requiredCardRenderer
- Function that renders the card into a container

Returns

() => void

Example

tsx
// Vanilla JS
pillar.registerCard('invite_members', (container, data, callbacks) => {
  container.innerHTML = `
    <div class="invite-card">
      <h3>Invite Team Members</h3>
      ${data.emails.map(e => `<div>${e}</div>`).join('')}
      <button id="confirm">Send Invites</button>
    </div>
  `;
  container.querySelector('#confirm').onclick = callbacks.onConfirm;
  return () => container.innerHTML = ''; // cleanup
});

Types

CardCallbacks

interface

Callbacks provided to custom card renderers.

typescript
interface CardCallbacks {
  /** Called when user confirms the action. Pass modified data if needed. */
  onConfirm: (modifiedData?: Record<string, unknown>) => void;
  /** Called when user cancels the action */
  onCancel: () => void;
  /** Called to report card state changes (for analytics/confirmation) */
  onStateChange?: (
    state: "loading" | "success" | "error",
    message?: string
  ) => void;
}

Properties

onConfirm
required(modifiedData?: Record<string, unknown>) => void
Called when user confirms the action. Pass modified data if needed.
onCancel
required() => void
Called when user cancels the action
onStateChange
( state: "loading" | "success" | "error", message?: string ) => void
Called to report card state changes (for analytics/confirmation)

CardFieldSchema

interface

Card field schema definition for declarative card configuration.

typescript
interface CardFieldSchema {
  /** Field name/key */
  name: string;
  /** Display label */
  label: string;
  /** Field type */
  type:
    | "text"
    | "number"
    | "email"
    | "select"
    | "multiselect"
    | "checkbox"
    | "textarea"
    | "date"
    | "hidden";
  /** Whether field is required */
  required?: boolean;
  /** Default value */
  defaultValue?: unknown;
  /** Placeholder text */
  placeholder?: string;
  /** Help text shown below field */
  helpText?: string;
  /** Options for select/multiselect types */
  options?: Array<{ value: string; label: string }>;
  /** Validation rules */
  validation?: {
    min?: number;
    max?: number;
    minLength?: number;
    maxLength?: number;
    pattern?: string;
    patternMessage?: string;
  };
}

Properties

name
requiredstring
Field name/key
label
requiredstring
Display label
type
required| "text" | "number" | "email" | "select" | "multiselect" | "checkbox" | "textarea" | "date" | "hidden"
Field type
required
boolean
Whether field is required
defaultValue
unknown
Default value
placeholder
string
Placeholder text
helpText
string
Help text shown below field
options
Array<{ value: string; label: string }>
Options for select/multiselect types
validation
{ min?: number; max?: number; minLength?: number; maxLength?: number; pattern?: string; patternMessage?: string; }
Validation rules

CardRegistrationOptions

interface

Enhanced card registration options.

typescript
interface CardRegistrationOptions {
  /** Card type identifier (e.g., 'add_to_deal', 'invite_member') */
  cardType: string;
  /** Human-readable card title */
  title?: string;
  /** Card description */
  description?: string;
  /** Schema defining form fields (for auto-generated forms) */
  schema?: CardFieldSchema[];
  /** Custom renderer function (overrides schema-based rendering) */
  renderer?: CardRenderer;
  /** Theme/styling options */
  theme?: {
    variant?: "default" | "compact" | "wide";
    confirmLabel?: string;
    cancelLabel?: string;
  };
}

Properties

cardType
requiredstring
Card type identifier (e.g., 'add_to_deal', 'invite_member')
title
string
Human-readable card title
description
string
Card description
schema
CardFieldSchema[]
Schema defining form fields (for auto-generated forms)
renderer
CardRenderer
Custom renderer function (overrides schema-based rendering)
theme
{ variant?: "default" | "compact" | "wide"; confirmLabel?: string; cancelLabel?: string; }
Theme/styling options

CardRenderer

type

Card renderer function signature. Customers register these to render custom confirmation cards.

typescript
type CardRenderer = (
  container: HTMLElement,
  data: Record<string, unknown>,
  callbacks: CardCallbacks
) => (() => void) | void