# Ghost Text
Inline suggestions for AI chat composers: the rest of the message in light gray as people type. Tab to accept.
[Live demo](https://hardflip.studio/ghost-text) · [Playground](https://hardflip.studio/ghost-text/playground/)
## Installation
With React:
```sh
npm install @ghosttext/core @ghosttext/react
```
Without a framework:
```sh
npm install @ghosttext/core @ghosttext/dom
```
For Chrome's on-device model, add `@ghosttext/chrome-ai`.
## Quick start
### React
```tsx
import { chromeAI } from '@ghosttext/chrome-ai';
import { cascade, history } from '@ghosttext/core';
import { useGhostText } from '@ghosttext/react';
const source = cascade(history(), chromeAI());
export function Composer({ messages, value, onChange, isStreaming }) {
const { ghostTextRef } = useGhostText({
source,
messages,
suggest: !isStreaming,
});
return (
);
}
```
With shadcn/ui, add a `GhostTextarea` built on your `Textarea`:
```sh
npx shadcn add https://hardflip.studio/ghost-text/r/ghost-textarea.json
```
```tsx
```
### Without a framework
```ts
import { history } from '@ghosttext/core';
import { ghostText } from '@ghosttext/dom';
const ghost = ghostText(textarea, { source: history() });
ghost.update({ messages, suggest: !isReplying });
ghost.destroy();
```
## Choosing a source
A source decides what to suggest. Combine them with `cascade()`: the first one that has something wins.
### Chrome AI, on the device
Free, private and offline once the model is downloaded. It suggests nothing where Chrome has no Prompt API.
```ts
import { chromeAI } from '@ghosttext/chrome-ai';
const source = chromeAI();
```
### Your own endpoint
The model and its key stay on your server.
```ts
import { endpoint } from '@ghosttext/core';
const source = endpoint({ url: '/api/ghost-text' });
```
Your server receives `{ context }` as JSON and streams text back. The [endpoint spec](docs/endpoint.md) has the details, and two recipes build it: with the [AI SDK](docs/recipes/backend-ai-sdk.md), or with plain `fetch` to the [OpenAI API](docs/recipes/backend-openai.md) and `gpt-6-luna`.
## Styling
The ghost text inherits the textarea's font. Change its color with one CSS variable, and keep 4.5:1 contrast against your background.
```css
textarea {
--ghost-text-color: rgb(0 0 0 / 0.6);
}
```
The composer carries `data-ghost-text-state`: `idle`, `loading` or `visible`.
```css
textarea[data-ghost-text-state='loading'] {
background: radial-gradient(circle, currentColor 2px, transparent 2px) right
12px top 12px / 8px 8px no-repeat;
}
```
## Accessibility
The textarea stays native, so value, caret and undo keep working. Each new suggestion is announced politely, `aria-keyshortcuts` lists the keys, and high contrast and forced colors are handled. On touch screens, tap the suggestion to accept it.
## Learn more
- [API reference](docs/api.md): every export, with its signature and an example.
- [Guide](docs/guide.md): keys, sources, plugins, styling and accessibility in depth.
- [Endpoint](docs/endpoint.md): the request and response your server handles.
- Recipes: [assistant-ui](docs/recipes/assistant-ui.md), the [AI SDK](docs/recipes/ai-sdk.md), [several composers](docs/recipes/several-composers.md), and backends with the [AI SDK](docs/recipes/backend-ai-sdk.md) or the [OpenAI API](docs/recipes/backend-openai.md).
- [Types](REFERENCE.md), generated from the declarations.
- [`llms.txt`](https://hardflip.studio/ghost-text/llms.txt) and the [agent skill](skills/ghost-text/SKILL.md) for coding agents.
- [Contributing](CONTRIBUTING.md).
## License
[MIT](LICENSE) © [François Chalifour](https://francoischalifour.com). A [Hardflip Studio](https://hardflip.studio) project.
---
# Guide
Ghost Text adds inline suggestions to a chat composer. People see the rest of their message in light gray, press Tab to take it, or keep typing. After the assistant replies, an empty composer predicts the next message.
## Install
```sh
npm install @ghosttext/core @ghosttext/dom
```
With React, install `@ghosttext/react` instead of `@ghosttext/dom`. For Chrome's on-device model, add `@ghosttext/chrome-ai`. Each package does one job, so an app ships only what it uses.
## Add it to a textarea
```ts
import { history } from '@ghosttext/core';
import { ghostText } from '@ghosttext/dom';
const ghost = ghostText(textarea, { source: history() });
```
`history()` suggests messages the person sent before. It is instant: it shows with no pause and needs no model, which makes it a good first source.
Pass the messages so sources can use it, and disable suggestions while the assistant replies:
```ts
ghost.update({ messages, suggest: !isReplying });
```
`messages` is a `{ role, content }[]`, oldest first. AI SDK `UIMessage`s (with `parts`) and assistant-ui messages work as they are. Only text parts are read, so files, images and tool calls are ignored, and files in past messages are not sent to a model. To include a draft attachment, read it in a custom source's closure.
`ghost.destroy()` removes everything and restores the textarea.
## React
```tsx
import { useGhostText } from '@ghosttext/react';
const { ghostTextRef, state } = useGhostText({
source,
messages,
suggest: !isReplying,
});
return (