> ## Documentation Index
> Fetch the complete documentation index at: https://blackbox.dasha.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize Widget Appearance and Behavior

> Customize widget appearance, themes, and behavior. Use CSS variables and JavaScript API for advanced control.

Make the widget match your brand. Customize colors, themes, and position using CSS variables. Control behavior with the JavaScript API.

**What you'll learn:** Theme and position options, feature gating, JavaScript API, event handling, CSS variables, and mobile optimization.

## Built-in customization

<Accordion title="Theme">
  ```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <!-- Light theme -->
  <blackbox-agent theme="light"></blackbox-agent>

  <!-- Dark theme -->
  <blackbox-agent theme="dark"></blackbox-agent>
  ```
</Accordion>

| Theme   | Best for                                   |
| ------- | ------------------------------------------ |
| `light` | Light-colored websites, minimalist designs |
| `dark`  | Dark-mode sites, tech products, dashboards |

<Accordion title="Position">
  ```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <!-- Bottom positions (recommended) -->
  <blackbox-agent position="bottom-right"></blackbox-agent>
  <blackbox-agent position="bottom-left"></blackbox-agent>
  <blackbox-agent position="bottom-center"></blackbox-agent>

  <!-- Top positions -->
  <blackbox-agent position="top-right"></blackbox-agent>
  <blackbox-agent position="top-left"></blackbox-agent>
  <blackbox-agent position="top-center"></blackbox-agent>
  ```
</Accordion>

<Tip>
  `bottom-right` is most familiar to users—it's where chat widgets typically appear.
</Tip>

***

## Feature gating

Control which features appear in the widget UI.

<Accordion title="Configuration">
  ```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <blackbox-agent
    skip-discovery
    data-config='{
      "features": ["AllowWebCall", "AllowWebChat"],
      "enableFeatureGating": true,
      "uiGatingMode": "hide"
    }'
  ></blackbox-agent>
  ```
</Accordion>

### Gating modes

| Mode      | Behavior                            |
| --------- | ----------------------------------- |
| `hide`    | Completely remove disabled features |
| `disable` | Show features grayed out            |

### Common configurations

<Tabs>
  <Tab title="Voice only">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "features": ["AllowWebCall"],
      "enableFeatureGating": true,
      "uiGatingMode": "hide"
    }
    ```
  </Tab>

  <Tab title="Chat only">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "features": ["AllowWebChat"],
      "enableFeatureGating": true,
      "uiGatingMode": "hide"
    }
    ```
  </Tab>

  <Tab title="All features">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "features": [
        "AllowWebCall",
        "AllowWebChat",
        "SendCallResult",
        "SendTranscriptForAudioCall"
      ],
      "enableFeatureGating": true,
      "uiGatingMode": "disable"
    }
    ```
  </Tab>
</Tabs>

***

## JavaScript API

Control the widget programmatically for advanced integrations.

<Accordion title="Get widget reference">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const widget = document.querySelector('blackbox-agent');
  ```
</Accordion>

<Accordion title="Open and close">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Open widget
  widget.open();

  // Close widget
  widget.close();

  // Toggle
  widget.toggle();
  ```
</Accordion>

<Accordion title="Trigger on events">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Open after scroll
  window.addEventListener('scroll', () => {
    if (window.scrollY > 500) widget.open();
  });

  // Open on button click
  document.getElementById('help-btn').addEventListener('click', () => {
    widget.open();
  });

  // Open for new visitors after delay
  if (!localStorage.getItem('returning')) {
    setTimeout(() => widget.open(), 5000);
    localStorage.setItem('returning', 'true');
  }
  ```
</Accordion>

***

## Event handling

React to widget events in your application.

<Accordion title="Available events">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const widget = document.querySelector('blackbox-agent');

  // Widget opened
  widget.addEventListener('widget-opened', (e) => {
    console.log('Widget opened');
  });

  // Widget closed
  widget.addEventListener('widget-closed', (e) => {
    console.log('Widget closed');
  });

  // Call started
  widget.addEventListener('call-started', (e) => {
    console.log('Call ID:', e.detail.callId);
    console.log('Type:', e.detail.callType); // 'voice' or 'chat'
  });

  // Call ended
  widget.addEventListener('call-ended', (e) => {
    console.log('Duration:', e.detail.duration);
    console.log('Status:', e.detail.status);
    showFeedbackForm();
  });

  // Error occurred
  widget.addEventListener('widget-error', (e) => {
    console.error('Error:', e.detail.error);
  });

  // Transcript update (if SendTranscriptForAudioCall enabled)
  widget.addEventListener('transcript-update', (e) => {
    console.log(`${e.detail.speaker}: ${e.detail.text}`);
  });

  // Tool executed (if SendToolCallLogs enabled)
  widget.addEventListener('tool-executed', (e) => {
    console.log('Tool:', e.detail.toolName);
    console.log('Result:', e.detail.result);
  });
  ```
</Accordion>

<Accordion title="Call result handling">
  When `SendCallResult` is enabled:

  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  widget.addEventListener('call-result', (e) => {
    const result = e.detail;

    if (result.data.appointment) {
      // Agent scheduled an appointment
      addToCalendar(result.data.appointment);
    }

    if (result.data.lead) {
      // Agent captured lead info
      sendToCRM(result.data.lead);
    }
  });
  ```
</Accordion>

***

## CSS customization

Override CSS variables for custom styling.

<Warning>
  CSS variable names may change in future versions. Test after widget updates.
</Warning>

<Accordion title="Available variables">
  ```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
  blackbox-agent {
    /* Primary brand color */
    --widget-primary-color: #4F46E5;

    /* Backgrounds */
    --widget-background: #FFFFFF;
    --widget-header-background: #F9FAFB;

    /* Text */
    --widget-text-primary: #111827;
    --widget-text-secondary: #6B7280;

    /* Borders */
    --widget-border-color: #E5E7EB;
    --widget-border-radius: 12px;

    /* Shadow */
    --widget-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);

    /* Buttons */
    --widget-button-background: #4F46E5;
    --widget-button-text: #FFFFFF;
    --widget-button-hover: #4338CA;

    /* Size */
    --widget-width: 380px;
    --widget-height: 600px;

    /* Position offset */
    --widget-offset-x: 20px;
    --widget-offset-y: 20px;
  }
  ```
</Accordion>

### Brand examples

<Tabs>
  <Tab title="Blue Enterprise">
    ```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
    blackbox-agent {
      --widget-primary-color: #0066CC;
      --widget-button-background: #0066CC;
      --widget-button-hover: #0052A3;
      --widget-border-radius: 8px;
    }
    ```
  </Tab>

  <Tab title="Green Vibrant">
    ```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
    blackbox-agent {
      --widget-primary-color: #10B981;
      --widget-button-background: #10B981;
      --widget-button-hover: #059669;
      --widget-border-radius: 16px;
    }
    ```
  </Tab>

  <Tab title="Orange Energy">
    ```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
    blackbox-agent {
      --widget-primary-color: #FF5722;
      --widget-button-background: #FF5722;
      --widget-button-hover: #E64A19;
      --widget-border-radius: 12px;
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Responsive sizing">
  ```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
  /* Default desktop */
  blackbox-agent {
    --widget-width: 380px;
    --widget-height: 600px;
  }

  /* Full screen on mobile */
  @media (max-width: 768px) {
    blackbox-agent {
      --widget-width: 100vw;
      --widget-height: 100vh;
      --widget-offset-x: 0;
      --widget-offset-y: 0;
    }
  }
  ```
</Accordion>

***

<Accordion title="Dynamic theme switching">
  Match user preferences or site theme:

  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const widget = document.querySelector('blackbox-agent');

  // Follow system preference
  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)');
  widget.setAttribute('theme', prefersDark.matches ? 'dark' : 'light');

  // Listen for changes
  prefersDark.addEventListener('change', (e) => {
    widget.setAttribute('theme', e.matches ? 'dark' : 'light');
  });
  ```
</Accordion>

***

## Mobile optimization

The widget automatically adapts to mobile:

* **Full-screen** when expanded
* **Touch-optimized** buttons
* **Prominent** microphone button
* **Swipe gestures** to close

### Mobile best practices

| Do                       | Avoid                           |
| ------------------------ | ------------------------------- |
| Use bottom positions     | Auto-open on load               |
| Prefer voice over typing | Use top-center (blocks nav)     |
| Test on actual devices   | Make minimized button too small |
| Allow easy dismissal     | Require extensive typing        |

<Accordion title="Mobile-specific config">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  function isMobile() {
    return /Android|iPhone|iPad|iPod/i.test(navigator.userAgent) ||
           window.innerWidth < 768;
  }

  if (isMobile()) {
    const widget = document.querySelector('blackbox-agent');
    widget.setAttribute('position', 'bottom-center');
  }
  ```
</Accordion>

***

## Use case examples

<Accordion title="Customer support">
  ```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <style>
    blackbox-agent.support {
      --widget-primary-color: #2563EB;
      --widget-border-radius: 8px;
    }
  </style>

  <blackbox-agent
    class="support"
    theme="light"
    position="bottom-right"
    data-config='{"features":["AllowWebCall","AllowWebChat"]}'
  ></blackbox-agent>

  <script>
    // Open if user is idle
    let idle = 0;
    setInterval(() => {
      if (++idle > 30) {
        document.querySelector('blackbox-agent').open();
        idle = 0;
      }
    }, 1000);
    document.addEventListener('mousemove', () => idle = 0);
  </script>
  ```
</Accordion>

<Accordion title="Lead capture">
  ```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <blackbox-agent
    theme="dark"
    position="bottom-center"
    data-config='{"features":["AllowWebCall","SendCallResult"]}'
  ></blackbox-agent>

  <script>
    const widget = document.querySelector('blackbox-agent');

    // Open after reading content
    setTimeout(() => widget.open(), 45000);

    // Capture lead data
    widget.addEventListener('call-result', (e) => {
      if (e.detail.data?.lead) {
        fetch('/api/leads', {
          method: 'POST',
          body: JSON.stringify(e.detail.data.lead)
        });
      }
    });
  </script>
  ```
</Accordion>

***

## Accessibility

The widget supports accessibility features:

| Feature                 | Support                     |
| ----------------------- | --------------------------- |
| **Keyboard navigation** | Tab to focus, Enter to open |
| **Screen readers**      | ARIA labels on controls     |
| **Focus management**    | Trapped when open           |
| **Escape key**          | Closes widget               |
| **High contrast**       | Supported                   |

<Tip>
  Enable `SendTranscriptForAudioCall` to provide text alternatives for voice calls.
</Tip>

***

## What's next

<CardGroup cols={2}>
  <Card title="Widget Configuration" icon="gear" href="/docs/deploy/widget-configuration">
    Configure security and features
  </Card>

  <Card title="Web Widget Embedding" icon="code" href="/docs/deploy/web-widget-embedding">
    Installation guides
  </Card>

  <Card title="Webhooks" icon="bell" href="/docs/webhooks-and-events/webhooks-overview">
    Handle events server-side
  </Card>

  <Card title="Call History" icon="chart-line" href="/docs/monitor/call-history">
    Track widget performance
  </Card>
</CardGroup>