# Terminal
> A typing terminal and an inline typewriter for rotating headlines.
Category: Text. Docs: https://neonkit.heyaadi.com/components/terminal
## Installation
```bash
npx shadcn@latest add https://neonkit.heyaadi.com/r/terminal.json
```
With the `@neonkit` namespace configured: `npx shadcn@latest add @neonkit/terminal`.
npm dependencies: none. Also needs `lib/utils.ts` (`cn`) and `lib/neon.ts` (`neonVars`), which the CLI adds.
## Usage
```tsx
import { Terminal, Typewriter } from "@/components/ui/terminal"
Neon UI for
```
## Examples
### Install session
Input lines type after the prompt, the rest print. loop starts over a few seconds after the end.
```tsx
import { Terminal } from "@/components/ui/terminal";
export default function TerminalDemo() {
return (
);
}
```
### Typewriter
Rotating words for a headline.
```tsx
import { Typewriter } from "@/components/ui/terminal";
export default function TerminalTypewriter() {
return (
// The rotating words get a line of their own, so the headline never reflows while they type.
Neon UI for
);
}
```
### Errors and a custom prompt
Without loop, a Replay button appears in the title bar when the session ends.
```tsx
import { Terminal } from "@/components/ui/terminal";
export default function TerminalDeploy() {
return (
);
}
```
## API reference
### Terminal
Also accepts native div attributes.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lines` | `TerminalLine[]` | — | The session, in order. |
| `title` | `ReactNode` | — | Shown in the title bar. |
| `typingSpeed` | `number` | `35` | Milliseconds per typed character, with a little human jitter. |
| `loop` | `boolean` | `false` | Start over 3s after the last line. |
| `startOnView` | `boolean` | `true` | Wait until it scrolls into view before typing. |
| `prompt` | `string` | `"$"` | Printed before every input line. |
| `color` | `NeonColor` | `inherited` | Prompt and caret color. |
| `onDone` | `() => void` | — | Called when the last line has printed: once per run, once per pass when looping, and right away under reduced motion. |
### TerminalLine
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `"input" \| "output" \| "success" \| "error" \| "comment"` | — | input is typed after the prompt; the others print in their own color. |
| `text` | `string` | — | The line. Long lines wrap at the terminal's edge. |
| `delay` | `number` | — | Milliseconds to wait before this line. Defaults to a short think before input and a beat after it. |
### Typewriter
Also accepts native attributes for the element it renders.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `words` | `string[]` | — | Typed, held, deleted and replaced in turn. |
| `loop` | `boolean` | `true` | Keep rotating. When false it stops on the last word. |
| `cursor` | `boolean` | `true` | A lit caret after the word. |
| `typeSpeed` | `number` | `70` | Milliseconds per typed character. |
| `deleteSpeed` | `number` | `40` | Milliseconds per deleted character. |
| `pause` | `number` | `1800` | Milliseconds a finished word stays up. |
| `as` | `"span" \| "p" \| "div" \| "h1" \| "h2" \| "h3" \| "h4"` | `"span"` | Element to render. |
| `color` | `NeonColor` | `inherited` | Word and caret color. |
## Accessibility
- The terminal renders the whole transcript once for screen readers, so nothing is announced per character.
- Typewriter gives screen readers all its words as one phrase instead of the one currently on screen.
- Space for every line is reserved up front, so the terminal doesn't grow while it types.
- Under reduced motion the terminal shows the finished session, and Typewriter swaps words without typing them.
## Source
`components/ui/terminal.tsx`
```tsx
"use client";
import * as React from "react";
import { cn } from "@/lib/utils";
import { neonVars, type NeonColor } from "@/lib/neon";
const css = `
@keyframes nk-terminal-blink { 0%, 49% { opacity: 1 } 50%, 100% { opacity: 0 } }
.nk-terminal-blink { animation: nk-terminal-blink 1.06s steps(1, end) infinite; }
[data-typing] > .nk-terminal-blink { animation: none; }
@media (prefers-reduced-motion: reduce) { .nk-terminal-blink { animation: none; } }
`;
const reducedQuery = "(prefers-reduced-motion: reduce)";
function subscribeReduced(onChange: () => void) {
const mq = window.matchMedia?.(reducedQuery);
mq?.addEventListener?.("change", onChange);
return () => mq?.removeEventListener?.("change", onChange);
}
function useReducedMotionPreference() {
return React.useSyncExternalStore(
subscribeReduced,
() => !!window.matchMedia?.(reducedQuery).matches,
() => false,
);
}
export type TerminalLine = {
/** `input` is typed after the prompt; everything else prints. */
kind: "input" | "output" | "success" | "error" | "comment";
text: string;
/** Milliseconds to wait before this line starts. */
delay?: number;
};
const kinds: Record = {
input: "text-white/90",
output: "text-white/55",
success: "text-[rgb(52_211_153)]",
error: "text-[rgb(255_77_94)]",
// Dimmer than output but still AA on the terminal's glass.
comment: "text-white/50",
};
function Caret({ blink, className }: { blink: boolean; className?: string }) {
return (
);
}
export interface TerminalProps
extends Omit, "color" | "title"> {
/** Shown in the title bar. */
title?: React.ReactNode;
/** The session, in order. */
lines: TerminalLine[];
/** Milliseconds per typed character, before a little human jitter. */
typingSpeed?: number;
/** Start over a few seconds after the last line. */
loop?: boolean;
/** Wait until the terminal scrolls into view before typing. */
startOnView?: boolean;
/** Printed before every input line. */
prompt?: string;
/** Palette name or any hex color. Inherits `--neon-accent` when omitted. */
color?: NeonColor;
/** Called when the last line has printed: once per run, and once per pass when looping. */
onDone?: () => void;
}
const Terminal = React.forwardRef(
(
{
className,
style,
color,
title,
lines,
typingSpeed = 35,
loop = false,
startOnView = true,
prompt = "$",
onDone,
...props
},
ref,
) => {
const rootRef = React.useRef(null);
const onDoneRef = React.useRef(onDone);
const typedRef = React.useRef(null);
const restRef = React.useRef(null);
const linesRef = React.useRef(lines);
React.useImperativeHandle(ref, () => rootRef.current as HTMLDivElement);
const reduced = useReducedMotionPreference();
const [started, setStarted] = React.useState(!startOnView);
const [run, setRun] = React.useState(0);
// Lines before `step` are printed; `step` itself is the one in progress.
const [step, setStep] = React.useState(0);
const [typing, setTyping] = React.useState(false);
const script = JSON.stringify(lines);
React.useEffect(() => {
linesRef.current = lines;
onDoneRef.current = onDone;
});
React.useEffect(() => {
const node = rootRef.current;
if (started || !node) return;
if (typeof IntersectionObserver === "undefined") {
const timer = setTimeout(() => setStarted(true));
return () => clearTimeout(timer);
}
const io = new IntersectionObserver(
([entry]) => {
if (!entry.isIntersecting) return;
io.disconnect();
setStarted(true);
},
{ threshold: 0.3 },
);
io.observe(node);
return () => io.disconnect();
}, [started]);
// Reduced motion prints the whole session at once, so it is done as soon as it starts.
React.useEffect(() => {
if (started && reduced) onDoneRef.current?.();
}, [started, reduced, run, script]);
React.useEffect(() => {
if (!started || reduced) return;
const session = linesRef.current;
let timer: ReturnType;
let index = 0;
const write = (text: string, count: number) => {
if (typedRef.current) typedRef.current.textContent = text.slice(0, count);
if (restRef.current) restRef.current.textContent = text.slice(count);
};
const next = () => {
setStep(index);
setTyping(false);
const line = session[index];
if (!line) {
onDoneRef.current?.();
if (loop) {
timer = setTimeout(() => {
index = 0;
next();
}, 3200);
}
return;
}
const previous = session[index - 1];
if (line.kind === "input") {
timer = setTimeout(() => {
setTyping(true);
let count = 0;
const type = () => {
count += 1;
write(line.text, count);
if (count >= line.text.length) {
// A beat on the finished line, as if reaching for Enter.
timer = setTimeout(() => {
index += 1;
next();
}, 360);
return;
}
// Deterministic jitter: 0.6x to 1.4x the base speed.
timer = setTimeout(type, typingSpeed * (0.6 + ((count * 7919) % 9) / 10));
};
timer = setTimeout(type, typingSpeed);
}, line.delay ?? (index === 0 ? 400 : 700));
} else {
timer = setTimeout(
() => {
index += 1;
next();
},
line.delay ?? (previous?.kind === "input" ? 420 : 90),
);
}
};
timer = setTimeout(next);
return () => clearTimeout(timer);
}, [started, reduced, run, loop, typingSpeed, script]);
const done = reduced || step >= lines.length;
const shown = reduced ? lines.length : step;
const transcript = lines
.map((line) => (line.kind === "input" ? `${prompt} ${line.text}` : line.text))
.join("\n");
return (
{title}
{!loop && !reduced && (
// Stays mounted while the session replays, so a keyboard user keeps focus on it.
)}
{/* The bar's lower edge powers up while a command is being typed */}
{transcript}
{/* Wrap at spaces first, and inside a word only when it can't fit on a line of its own. */}
{lines.map((line, i) => {
const input = line.kind === "input";
if (i === shown && input) {
return (