docs/developer_docs/extensions/extension-points/chat.md

---
title: Chat
sidebar_position: 3
---

<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
-->

# Chat Contributions

Extensions can add a chat interface to Superset by registering a trigger and a panel. The host owns the layout, open/close state, and display mode — the extension only needs to provide the UI components.

## Overview

A chat registration consists of two React components:

| Component   | Role                                                                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Trigger** | Always-visible entry point (e.g., a floating button). Rendered in the bottom-right corner in floating mode, or as a fixed overlay in panel mode. |
| **Panel**   | The chat UI itself (message list, input, etc.). Mounted by the host in the active display mode.                                                  |

## Display Modes

The host supports two display modes, switchable by the user or the extension at runtime:

| Mode       | Behavior                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------- |
| `floating` | Panel floats above page content, anchored to the bottom-right corner.                                         |
| `panel`    | Panel is docked to the right side of the application as a resizable sidebar, sitting beside the page content. |

The user's last selected mode and open/closed state are persisted across page reloads.

## Registering a Chat

Call `chat.registerChat` from your extension's entry point with a descriptor, a trigger factory, and a panel factory:

```tsx
import { chat } from '@apache-superset/core';
import ChatTrigger from './ChatTrigger';
import ChatPanel from './ChatPanel';

chat.registerChat(
  { id: 'my-org.my-chat', name: 'My Chat' },
  ChatTrigger,
  ChatPanel,
);
```

Only one chat registration is active at a time. If a second extension calls `registerChat`, it replaces the first and a warning is logged.

## Opening and Closing the Chat

The trigger component is responsible for toggling the panel. Use `chat.isOpen()`, `chat.open()`, and `chat.close()` to control visibility:

```tsx
import { chat } from '@apache-superset/core';

export default function ChatTrigger() {
  return (
    <button onClick={() => (chat.isOpen() ? chat.close() : chat.open())}>
      💬
    </button>
  );
}
```

You can also subscribe to open/close events from any component:

```tsx
useEffect(() => {
  const { dispose } = chat.onDidOpen(() => console.log('chat opened'));
  return dispose;
}, []);
```

## Changing the Display Mode

Call `chat.setDisplayMode` to switch between `'floating'` and `'panel'` modes. In your panel component, subscribe to `onDidChangeDisplayMode` to react to changes (including those triggered by the user):

```tsx
import { useState, useEffect } from 'react';
import { chat } from '@apache-superset/core';

export default function ChatPanel() {
  const [mode, setMode] = useState(chat.getDisplayMode());

  useEffect(() => {
    const { dispose } = chat.onDidChangeDisplayMode(m => setMode(m));
    return dispose;
  }, []);

  return (
    <div style={{ height: mode === 'panel' ? '100%' : '80vh' }}>
      <button
        onClick={() =>
          chat.setDisplayMode(mode === 'panel' ? 'floating' : 'panel')
        }
      >
        {mode === 'panel' ? 'Float' : 'Dock'}
      </button>
      {/* message list and input */}
    </div>
  );
}
```

## Chat API Reference

All methods are available on the `chat` namespace from `@apache-superset/core`:

| Method / Event                             | Description                                                                                                                               |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `registerChat(descriptor, trigger, panel)` | Register a chat extension. Returns a `Disposable` to unregister.                                                                          |
| `open()`                                   | Open the chat panel. No-op if already open or no registration.                                                                            |
| `close()`                                  | Close the chat panel.                                                                                                                     |
| `isOpen()`                                 | Returns `true` if the panel is currently open.                                                                                            |
| `getDisplayMode()`                         | Returns the current display mode (`'floating'` or `'panel'`).                                                                             |
| `setDisplayMode(mode)`                     | Switch between `'floating'` and `'panel'` mode.                                                                                           |
| `onDidOpen(listener)`                      | Subscribe to panel open events. Returns a `Disposable`.                                                                                   |
| `onDidClose(listener)`                     | Subscribe to panel close events. Returns a `Disposable`.                                                                                  |
| `onDidChangeDisplayMode(listener)`         | Subscribe to display mode changes. Returns a `Disposable`.                                                                                |
| `onDidRegisterChat(listener)`              | Subscribe to registration events.                                                                                                         |
| `onDidUnregisterChat(listener)`            | Subscribe to unregistration events.                                                                                                       |
| `onDidResizePanel(listener)`               | Subscribe to panel resize events (panel mode only). Not all hosts provide a resizer — do not rely on this firing. Returns a `Disposable`. |

## Next Steps

- **[Contribution Types](../contribution-types.md)** — Explore other contribution types
- **[Development](../development.md)** — Set up your development environment