Theming & Branding

Customize the panel appearance to match your application's design.

Basic setup

examples/guides/theme/basic-setup.tsx

<PillarProvider
  agentSlug="your-agent-slug"
  config={{
    theme: {
      mode: 'auto',
      colors: {
        primary: '#2563eb',
      },
    },
  }}
>

Color Mode

Value	Description
`'auto'`	Follow system preference (default)
`'light'`	Always light mode
`'dark'`	Always dark mode

Auto Mode

examples/guides/theme/auto-mode.tsx

theme: {
  mode: 'auto', // Respects prefers-color-scheme
}

Fixed Mode

examples/guides/theme/fixed-mode.tsx

theme: {
  mode: 'dark', // Always dark
}

Color Customization

Available Colors

examples/guides/theme/available-colors.tsx

theme: {
  colors: {
    primary: '#2563eb',         // Brand color (buttons, links)
    primaryHover: '#1d4ed8',    // Hover state
    background: '#ffffff',       // Main background
    backgroundSecondary: '#f9fafb', // Cards, inputs
    text: '#111827',            // Primary text
    textMuted: '#6b7280',       // Secondary text
    border: '#e5e7eb',          // Borders
    borderLight: '#f3f4f6',     // Subtle borders
  },
  darkColors: {
    primary: '#3b82f6',
    primaryHover: '#60a5fa',
    background: '#111827',
    backgroundSecondary: '#1f2937',
    text: '#f9fafb',
    textMuted: '#9ca3af',
    border: '#374151',
    borderLight: '#1f2937',
  },
}

Minimal Customization

Just set your brand color:

examples/guides/theme/minimal-customization.tsx

theme: {
  colors: { primary: '#8b5cf6' },
  darkColors: { primary: '#a78bfa' },
}

Runtime Updates

Change the theme at runtime:

examples/guides/theme/runtime-updates.tsx

const { setTheme } = usePillar();

// Toggle mode
setTheme({ mode: isDarkMode ? 'dark' : 'light' });

// Update colors
setTheme({ colors: { primary: '#10b981' } });

Sync with Your App

examples/guides/theme/sync-with-app.tsx

function ThemeSync() {
  const { setTheme } = usePillar();
  const { theme } = useTheme(); // Your app's theme hook
  
  useEffect(() => {
    setTheme({ mode: theme === 'dark' ? 'dark' : 'light' });
  }, [theme, setTheme]);
  
  return null;
}

Custom CSS

Inject custom CSS for advanced styling:

examples/guides/theme/custom-css.tsx

config={{
  customCSS: `
    .pillar-header {
      padding: 20px;
      border-bottom: 2px solid var(--pillar-primary);
    }
    
    .pillar-message-user {
      border-radius: 16px;
    }
    
    .pillar-button {
      font-weight: 600;
    }
  `,
}}

Available CSS Classes

Class	Element
`.pillar-panel`	Main panel container
`.pillar-header`	Panel header
`.pillar-content`	Content area
`.pillar-message-user`	User message bubble
`.pillar-message-assistant`	AI message bubble
`.pillar-chat-input`	Chat input field
`.pillar-task-button`	Task action buttons
`.pillar-confirm-action-card`	Confirmation card components

CSS Variables

examples/guides/theme/css-variables.css

.pillar-panel {
  --pillar-primary: #2563eb;
  --pillar-primary-hover: #1d4ed8;
  --pillar-bg: #ffffff;
  --pillar-bg-secondary: #f9fafb;
  --pillar-text: #111827;
  --pillar-text-muted: #6b7280;
  --pillar-border: #e5e7eb;
}

Best Practices

Maintain Contrast

Ensure text is readable:

examples/guides/theme/maintain-contrast.tsx

// ❌ Low contrast
colors: {
  text: '#aaaaaa',
  background: '#ffffff',
}

// ✅ Good contrast
colors: {
  text: '#374151',
  background: '#ffffff',
}

Test Both Modes

If using mode: 'auto', test in both light and dark:

examples/guides/theme/test-both-modes.tsx

// For testing
setTheme({ mode: 'light' });
// Verify...
setTheme({ mode: 'dark' });
// Verify...
setTheme({ mode: 'auto' }); // Reset

Next Steps

Customizing the Panel — Configure panel position, mode, and layout
Building Inline UI — Inline UI components inherit your theme automatically

Search documentation