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