Skip to content

Commit 258ae9e

Browse files
damlayildizdamlayildiz
committed
feat: custom trigger button for chatbot
1 parent 59eca9f commit 258ae9e

File tree

8 files changed

+526
-116
lines changed

8 files changed

+526
-116
lines changed

‎README.md‎

Lines changed: 149 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,18 @@
22

33
[![Status](https://img.shields.io/badge/status-in%20development-yellow)](https://github.com/sqliteai/docs-chatbot)
44

5-
Documentation search chatbot powered by SQLite and AI.
5+
AI-powered documentation search chatbot that integrates seamlessly into your application.
66

7-
## Prerequisites
7+
## Quick Start
8+
9+
### Prerequisites
810

911
Before using this chatbot, you need to:
1012

1113
1. **Index your documentation** - Use the [SQLite AI Search Action](https://github.com/sqliteai/sqlite-aisearch-action) to create embeddings from your documentation files
1214
2. **Create an edge function** - Follow the [setup guide](https://github.com/sqliteai/sqlite-aisearch-action#create-the-search-edge-function) to deploy the search edge function
1315

14-
## Usage
15-
16-
### React Application
16+
### React
1717

1818
```bash
1919
npm install @sqliteai/docs-chatbot
@@ -26,15 +26,15 @@ import "@sqliteai/docs-chatbot/style.css";
2626
function App() {
2727
return (
2828
<DocsChatbot
29-
searchUrl="your-edge-function-url"
29+
searchUrl="https://yourproject.sqlite.cloud/v2/functions/aisearch-docs"
3030
apiKey="your-api-key"
31-
title="Your Docs"
31+
title="Help Center"
3232
/>
3333
);
3434
}
3535
```
3636

37-
### Vanilla JavaScript / HTML
37+
### Vanilla JavaScript
3838

3939
```html
4040
<!DOCTYPE html>
@@ -47,43 +47,123 @@ function App() {
4747
<script src="https://unpkg.com/@sqliteai/docs-chatbot/dist/umd/docs-chatbot.min.js"></script>
4848

4949
<docs-chatbot
50-
search-url="your-edge-function-url"
50+
search-url="https://yourproject.sqlite.cloud/v2/functions/aisearch-docs"
5151
api-key="your-api-key"
52-
title="Your Docs"
52+
title="Help Center"
5353
>
5454
</docs-chatbot>
5555
</body>
5656
</html>
5757
```
5858

59-
**With dynamic configuration:**
59+
## Trigger Modes
60+
61+
The chatbot supports two trigger modes to fit different use cases.
62+
63+
### Default Trigger
64+
65+
**When to use:** Most common use case. Adds a floating button in the bottom-right corner that opens the chatbot when clicked.
66+
67+
```tsx
68+
<DocsChatbot
69+
searchUrl="your-edge-function-url"
70+
apiKey="your-api-key"
71+
title="Help Center"
72+
/>
73+
```
74+
75+
The floating button appears on every page and the dialog opens in the bottom-right corner.
76+
77+
### Custom Trigger
78+
79+
**When to use:** You want full control over when and how the chatbot opens. Perfect for:
80+
81+
- Adding help buttons in specific locations (headers, sidebars, toolbars)
82+
- Opening the chatbot programmatically
83+
- Integrating with existing UI patterns
84+
- Pages where the floating button would overlap with other elements
85+
86+
**React:**
87+
88+
```tsx
89+
import { DocsChatbot } from "@sqliteai/docs-chatbot";
90+
import "@sqliteai/docs-chatbot/style.css";
91+
import { useState } from "react";
92+
93+
function App() {
94+
const [open, setOpen] = useState(false);
95+
96+
return (
97+
<>
98+
{/* Your custom button anywhere in your app */}
99+
<button onClick={() => setOpen(true)}>Help & Support</button>
100+
101+
{/* Chatbot with custom trigger mode */}
102+
<DocsChatbot
103+
searchUrl="your-edge-function-url"
104+
apiKey="your-api-key"
105+
title="Help Center"
106+
trigger="custom"
107+
open={open}
108+
onOpenChange={setOpen}
109+
/>
110+
</>
111+
);
112+
}
113+
```
114+
115+
**Vanilla JavaScript:**
60116

61117
```html
62118
<script src="https://unpkg.com/@sqliteai/docs-chatbot/dist/umd/docs-chatbot.min.js"></script>
63119

64-
<docs-chatbot title="Your Docs"> </docs-chatbot>
120+
<!-- Your custom button -->
121+
<button id="help-btn">Help & Support</button>
122+
123+
<!-- Chatbot with custom trigger mode -->
124+
<docs-chatbot
125+
search-url="your-edge-function-url"
126+
api-key="your-api-key"
127+
title="Help Center"
128+
trigger="custom"
129+
>
130+
</docs-chatbot>
65131

66132
<script>
67133
const chatbot = document.querySelector("docs-chatbot");
68-
chatbot.setAttribute("search-url", "your-edge-function-url");
69-
chatbot.setAttribute("api-key", "your-api-key");
134+
const button = document.getElementById("help-btn");
135+
136+
// Open chatbot when button is clicked
137+
button.addEventListener("click", () => {
138+
chatbot.open = true;
139+
});
140+
141+
// Listen to state changes (optional)
142+
chatbot.addEventListener("openchange", (e) => {
143+
console.log("Chatbot open:", e.detail.open);
144+
});
70145
</script>
71146
```
72147

73-
## Props / Configuration
148+
## API Reference
149+
150+
### React Component Props
74151

75-
### React Component
152+
| Property | Type | Required | Description |
153+
| ------------------------ | ------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
154+
| `searchUrl` | `string` | Yes | Full URL of your deployed SQLite Cloud edge function (e.g., `https://yourproject.sqlite.cloud/v2/functions/aisearch-docs`) |
155+
| `apiKey` | `string` | Yes | SQLite Cloud API key with permissions to execute the edge function |
156+
| `title` | `string` | Yes | Title displayed in the chatbot header |
157+
| `emptyState` | `object` | No | Customizes the initial empty state of the chatbot |
158+
| `emptyState.title` | `string` | No | Main heading shown before the first message |
159+
| `emptyState.description` | `string` | No | Subtext shown below the empty state title |
160+
| `trigger` | `"default" \| "custom"` | No | Trigger mode: `"default"` uses floating button, `"custom"` requires you to control `open` state (default: `"default"`) |
161+
| `open` | `boolean` | Yes when `trigger="custom"` | Control the chatbot open state (only used with `trigger="custom"`) |
162+
| `onOpenChange` | `(open: boolean) => void` | Yes when `trigger="custom"` | Callback fired when the open state changes (only used with `trigger="custom"`) |
76163

77-
| Property | Type | Required | Description |
78-
| ------------------------ | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
79-
| `searchUrl` | `string` | Yes | Full URL of your deployed SQLite Cloud edge function (e.g., `https://yourproject.sqlite.cloud/v2/functions/aisearch-docs`) |
80-
| `apiKey` | `string` | Yes | SQLite Cloud API key with permissions to execute the edge function |
81-
| `title` | `string` | Yes | Title displayed in the chatbot header |
82-
| `emptyState` | `object` | No | Customizes the initial empty state of the chatbot |
83-
| `emptyState.title` | `string` | No | Main heading shown before the first message |
84-
| `emptyState.description` | `string` | No | Subtext shown below the empty state title |
164+
### Web Component
85165

86-
### Web Component Attributes
166+
#### Attributes
87167

88168
| Attribute | Required | Description |
89169
| ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
@@ -92,41 +172,51 @@ function App() {
92172
| `title` | Yes | Title displayed in the chatbot header |
93173
| `empty-state-title` | No | Main heading shown before the first message |
94174
| `empty-state-description` | No | Subtext shown below the empty state title |
175+
| `trigger` | No | Trigger mode: `"default"` uses floating button, `"custom"` requires controlling `open` property (default: `"default"`) |
95176

96-
## Customizing Theme
177+
#### Properties
97178

98-
You can customize the chatbot's appearance by overriding CSS variables.
179+
| Property | Type | Description |
180+
| -------- | --------- | --------------------------------------------------------------- |
181+
| `open` | `boolean` | Get or set the chatbot open state (property-only, no attribute) |
99182

100-
### Available CSS Variables
183+
#### Events
101184

102-
```css
103-
/* Border radius */
104-
--docs-chatbot-radius
105-
106-
/* Colors */
107-
--docs-chatbot-background
108-
--docs-chatbot-foreground
109-
--docs-chatbot-card
110-
--docs-chatbot-card-foreground
111-
--docs-chatbot-popover
112-
--docs-chatbot-popover-foreground
113-
--docs-chatbot-primary
114-
--docs-chatbot-primary-foreground
115-
--docs-chatbot-secondary
116-
--docs-chatbot-secondary-foreground
117-
--docs-chatbot-muted
118-
--docs-chatbot-muted-foreground
119-
--docs-chatbot-accent
120-
--docs-chatbot-accent-foreground
121-
--docs-chatbot-destructive
122-
--docs-chatbot-border
123-
--docs-chatbot-input
124-
--docs-chatbot-ring
125-
```
185+
| Event | Detail | Description |
186+
| ------------ | ------------------- | ----------------------------------------- |
187+
| `openchange` | `{ open: boolean }` | Fired when the chatbot open state changes |
126188

127-
### Usage Examples
189+
## Theming
128190

129-
**In your global CSS (recommended):**
191+
Customize the chatbot's appearance using CSS variables.
192+
193+
### CSS Variables
194+
195+
| Variable | Description |
196+
| ------------------------------------- | ------------------------ |
197+
| `--docs-chatbot-radius` | Border radius |
198+
| `--docs-chatbot-background` | Background color |
199+
| `--docs-chatbot-foreground` | Text color |
200+
| `--docs-chatbot-primary` | Primary color |
201+
| `--docs-chatbot-primary-foreground` | Primary text color |
202+
| `--docs-chatbot-secondary` | Secondary color |
203+
| `--docs-chatbot-secondary-foreground` | Secondary text color |
204+
| `--docs-chatbot-muted` | Muted color |
205+
| `--docs-chatbot-muted-foreground` | Muted text color |
206+
| `--docs-chatbot-accent` | Accent color |
207+
| `--docs-chatbot-accent-foreground` | Accent text color |
208+
| `--docs-chatbot-border` | Border color |
209+
| `--docs-chatbot-input` | Input background color |
210+
| `--docs-chatbot-ring` | Focus ring color |
211+
| `--docs-chatbot-card` | Card background color |
212+
| `--docs-chatbot-card-foreground` | Card text color |
213+
| `--docs-chatbot-popover` | Popover background color |
214+
| `--docs-chatbot-popover-foreground` | Popover text color |
215+
| `--docs-chatbot-destructive` | Destructive/error color |
216+
217+
### Examples
218+
219+
**React:**
130220

131221
```css
132222
/* In your main CSS file, import the chatbot styles first */
@@ -137,11 +227,10 @@ You can customize the chatbot's appearance by overriding CSS variables.
137227
--docs-chatbot-primary: oklch(0.6 0.2 0);
138228
--docs-chatbot-primary-foreground: oklch(1 0 0);
139229
--docs-chatbot-border: oklch(0.85 0 0);
230+
--docs-chatbot-radius: 8px;
140231
}
141232
```
142233

143-
**In React:**
144-
145234
```tsx
146235
import { DocsChatbot } from "@sqliteai/docs-chatbot";
147236
import "./styles.css"; // Your CSS file with overrides
@@ -151,27 +240,28 @@ function App() {
151240
<DocsChatbot
152241
searchUrl="your-edge-function-url"
153242
apiKey="your-api-key"
154-
title="Your Docs"
243+
title="Help Center"
155244
/>
156245
);
157246
}
158247
```
159248

160-
**In Vanilla JavaScript / HTML:**
249+
**Vanilla JavaScript:**
161250

162251
```html
163252
<style>
164253
docs-chatbot {
165254
--docs-chatbot-primary: oklch(0.6 0.2 0);
166255
--docs-chatbot-primary-foreground: oklch(1 0 0);
167256
--docs-chatbot-border: oklch(0.85 0 0);
257+
--docs-chatbot-radius: 8px;
168258
}
169259
</style>
170260

171261
<docs-chatbot
172262
search-url="your-edge-function-url"
173263
api-key="your-api-key"
174-
title="Your Docs"
264+
title="Help Center"
175265
>
176266
</docs-chatbot>
177267
```

0 commit comments

Comments
 (0)