chat-minimap

A small React library for rendering a turn-aware navigation strip alongside long AI chats. Each horizontal bar represents a chat turn, can encode a signal such as length or recency, previews on hover, and scrolls to the matching chat turn on click.

Install

pnpm add chat-minimap
# or
npm install chat-minimap

import { ChatMinimap } from "chat-minimap";
import "chat-minimap/styles.css";

<ChatMinimap
  turns={messages}
  getTurnId={(turn) => turn.id}
  getTurnText={(turn) => `${turn.userText} ${turn.assistantText}`}
  encoding="length"
  position="right"
  overflow="auto"
  offset={72}
  gap={2}
  radius={3}
  theme="blue"
  colorRamp={(intensity) => `oklch(${0.86 - intensity * 0.2} 0.13 190)`}
  ringColor="var(--ring)"
/>;

Mark each turn element in your chat with the same ID:

<article data-chat-turn-id={turn.id}>
  <UserBubble>{turn.userText}</UserBubble>
  <AssistantBubble>{turn.assistantText}</AssistantBubble>
</article>

API

ChatMinimap<T> accepts:

• turns: array of chat turns
• getTurnId: returns a stable turn ID
• getTurnText: returns text used for preview and default encoding
• encoding: "length", "recency", "uniform", or a custom function
• position: "right" or "left"
• overflow: "auto", "scroll", or "visible"; default "auto" keeps long rails internally scrollable
• offset: scroll offset in pixels, default 30; set this to your sticky chat header height plus desired padding
• thresholds: legacy IntersectionObserver thresholds accepted for compatibility
• previewLength: default 40
• mode: "query", "response", or "both" for label wording
• gap: vertical gap between bars; numbers are pixels, default 2
• radius: bar border radius; numbers are pixels, default "999px"
• theme: "default", "neutral", "zinc", "slate", "stone", "red", "orange", "yellow", "green", "blue", or "violet"
• colorRamp: maps intensity to a default CSS color for bars
• ringColor: active and focus ring color
• onBeforeScroll, onScrollEnd: hooks for host app scroll coordination
• renderTooltip: optional tooltip wrapper slot

Per-turn encoding(...).color overrides colorRamp for that bar. colorRamp overrides theme colors, and ringColor overrides the theme ring.

For sticky chat headers, measure the header bottom and pass it as offset, for example:

const offset = Math.ceil(header.getBoundingClientRect().bottom + 16);

For long conversations, keep the default overflow="auto". The rail stays bounded to the viewport and scrolls internally when all bars cannot fit, while the active bar is kept in view. Full virtualization/windowing for 1000+ turns is future work; the current behavior keeps one accessible button per turn.

Headless primitives are available from chat-minimap/headless.

shadcn registry

The repo includes a shadcn registry item. After deploying the demo to Vercel, install the copied Tailwind component with:

pnpm dlx shadcn@latest add https://<vercel-domain>/r/chat-minimap.json

Build the hosted registry JSON before deployment:

pnpm registry:build

The generated item is served by the Next.js demo from public/r/chat-minimap.json.

Development

pnpm install
pnpm check
pnpm test:e2e
pnpm demo:dev

Package and demo builds are intentionally separate:

pnpm build       # npm package build with tsup
pnpm demo:build  # Next.js demo build for Vercel, including registry JSON

Before publishing:

pnpm check
pnpm test:e2e
npm pack --dry-run
npm publish