ask-widget

A lightweight chat widget for developer portfolios. Drop-in floating chat with SSE streaming, dark/light themes, and configurable positioning. Aligned with the neutral zinc palette.

---

Links

	URL
🌐 Demo	Demo
📦 NPM	NPM
📚 Documentation	Project Documentation
🎨 Storybook	Storybook
👤 Portfolio	About me
☕ Support	Buy me a coffee

---

📖 Full Documentation

Visit the ask-widget documentation site for full details on API, theming, and standalone hooks.

---

Installation

npm install @chitrank2050/ask-widget
# or
pnpm add @chitrank2050/ask-widget

---

Quick Start

import { ChatWidget } from '@chitrank2050/ask-widget'
import '@chitrank2050/ask-widget/styles.css'

export default function Portfolio() {
  return (
    <main>
      <ChatWidget
        apiUrl="https://your-api.example.com"
        apiToken={import.meta.env.VITE_CHAT_API_TOKEN}
        position="bottom-right"
        theme="dark"
        title="Ask AI"
      />
    </main>
  )
}

Usage with Next.js (App Router)

To avoid React Hydration Mismatch errors in Server-Rendered frameworks, you must import the widget dynamically with SSR disabled. Create a wrapper Client Component:

// src/components/ClientChatWidget.tsx
"use client";

import dynamic from "next/dynamic";
import "@chitrank2050/ask-widget/styles.css";

const ChatWidget = dynamic(
  () => import("@chitrank2050/ask-widget").then((mod) => mod.ChatWidget),
  { ssr: false }
);

export default function ClientChatWidget() {
  return (
    <ChatWidget
      apiUrl="https://your-api.example.com"
      title="Ask AI"
    />
  );
}

You can then freely import and use <ClientChatWidget /> in your layout.tsx or any Server Component!

---

Features

• ⚡ SSE Streaming: Built-in support for token-by-token streaming via Server-Sent Events.
• 🎨 Zinc Aesthetic: Strictly monochrome. Designed to match modern developer portfolios.
• 🧩 Configurable API: Control themes, initial messages, placeholders, and positions.
• 🛠 Demo Mode: Built-in fallback stream if no API is configured.
• 🧩 Headless Hooks: Build your own UI with useChat, useSSEStream, and useSession.

---

Core Props

Prop	Type	Default	Description
apiUrl	string	—	Base URL of your chat API.
apiToken	string	—	Bearer token for API auth.
position	"bottom-right" | "bottom-left" | "bottom-center"	"bottom-right"	Widget position on screen.
theme	"dark" | "light"	"dark"	Color theme preset.
title	string	"Ask AI"	Header title.
placeholder	string	"Ask me anything..."	Input placeholder.
initialMessage	string	"Hello! How can I help you today?"	First message shown on open.

---

Developed by Chitrank Agnihotri