# Code viewer
> A file in a small card, line-numbered and coloured, with a Code | Diff switch that shows what changed as a unified diff.
A listing the way an agent shows the file it just edited. The card names the file and copies it in one press; the switch below turns the same file into a unified diff against its previous version: removed lines on red with a hatched edge, added ones on green, the changed value marked inside its line, and the counts in the header. The highlighter and the diff are a few dozen lines of their own, with no dependency.
A React component by Bruno Delorence: https://brunodelorence.com/components/code-viewer. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: AI.
## Anatomy
1. **Card**: The file in a card, 420 px at most, centred on a soft stage (white by day, a step above graphite at night). Long lines wrap rather than scroll.
2. **File name**: An icon and the name in mono, cut with an ellipsis when it is too long for the header.
3. **Counts**: In Diff the header trades Copy for the lines added and removed, green and red.
4. **Line number**: A 20 px column in the quiet ink, with a hairline down the gutter. In Diff a removed line keeps its old number.
5. **Removed line**: A red tint with a hatched edge, so the change reads without colour too; a screen reader hears “Removed:”.
6. **Added line**: A green tint with a solid edge, heard as “Added:”. Its number is the line’s place in the new file.
7. **Changed value**: Inside a line that mostly stayed, the tokens that differ sit on a stronger chip of the row’s colour.
8. **View switch**: Code | Diff as tabs: the chosen one raised in the track, 150 ms. Arrow keys, Home and End move between them.
## When to use
- A short file or snippet shown in a chat, a doc or a review: up to a few dozen lines, read in place.
- An agent’s proposed edit, where the reader wants both the result and what changed: Code shows the file, Diff the change.
- A small change to a familiar file, where the changed value is marked inside its line so `-14C` → `-16C` reads at a glance.
- Code meant to be copied as a whole: one Copy in the header, confirmed in green.
## When not to use
- Long files or several files at once. Use an editor or a review tool with folding, search and a file tree.
- Code the reader should edit. This is a listing to read; use an editor or a code field.
- Side-by-side reviews or diffs with many hunks: a unified diff of one short file is all it draws.
- Languages far from JavaScript and TypeScript: its small tokenizer knows their keywords only. Use a full highlighter.
- A command or a single line inside a sentence. Inline `code` is enough.
## Installation
Install it with the shadcn CLI, into components/code-viewer of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/code-viewer.json
```
Or copy all the source files below into one folder of your project. Either way it needs React 19 and a bundler with CSS Modules (Next.js, Vite).
It has a dark colour scheme. Its colours are CSS light-dark() pairs, kept inside @supports so that builds which rewrite light-dark() for older browsers leave them alone: it follows your page’s color-scheme (light unless the page sets one) or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
## Usage
```tsx
import { CodeViewer } from './code-viewer';
const before = `export function total(items) {
return items.reduce((sum, item) => sum + item.price, 0);
}
`;
const after = `export function total(items) {
return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}
`;
export function EditedFile() {
return (
);
}
```
## States
- **Code**: The file as it is now, with its numbers and colours, and Copy in the header.
- **Copied**: After Copy has written to the clipboard: a green check and Copied for 1.5 s, announced politely.
- **Diff**: The same file against `previous`, as a unified diff: removed lines first, then the added ones, with the counts in the header.
- **No previous version**: With `previous={null}` there is nothing to compare: no switch, only the listing and Copy.
- **Dark**: Every colour is a `light-dark()` token: a graphite stage, the card a step lighter, tints made translucent.
## How it works
- Each line is a grid row: a 20 px column of numbers and the code, with a 1 px hairline down the gutter drawn once for the whole listing. Long lines wrap where they must (pre-wrap and break-word), so the card never scrolls sideways, down to a phone.
- The colours come from one regular expression that splits a line into comments, strings, numbers, words, spaces and marks. A word is a keyword if it is in a short list, a call if the next mark after it opens a parenthesis, and plain otherwise: keywords take the accent, calls the strong ink at weight 500, strings and numbers orange, the rest the quiet ink.
- The diff is a longest common subsequence over whole lines, walked back into hunks listed as a unified diff lists them: the removed lines, then the added ones. Removed rows keep their old number, the others take the new one, and the header trades Copy for the counts.
- A removed line followed by an added one is compared token by token from both ends; when most of it stayed the same, the tokens in between sit on a chip of their colour at 18 % (color-mix), so “-14C” to “-16C” reads at a glance. A line that changed throughout is simply removed and added.
- Switching is instant, as a listing should be. Only the switch eases: the chosen button raises in 150 ms (background, colour and shadow on the standard ease), and the Copy button eases its colours in 100 ms. Copy writes the code with the Clipboard API and turns into a green Copied with a tick for 1.5 s.
- The changed rows paint above the gutter’s hairline, so their tints run edge to edge; the removed edge is a 3 px repeating 45° gradient, the added one solid.
- While on screen and untouched, a demo presses Copy, flips to the diff and back, on a loop; it lights each button as a pointer would just before pressing it, never touches the clipboard and is never announced. Any press, key or wheel hands the viewer to the reader, on the view the demo was showing.
- Every colour is a light-dark() token on the root, so the viewer follows the page’s color-scheme or the colorScheme prop. The card’s shadow is written once with all its layers, those a scheme does not use being transparent: a long soft lift by day, a short dark one at night.
## API reference
- **code** (`string`, default `a sample file`): The file as it is now: the listing, and what Copy copies.
- **previous** (`string | null`, default `the sample’s earlier version`): The file before the change; the diff compares it with code. null shows the listing alone, without the switch.
- **filename** (`string`, default `'churn.ts'`): The name in the header.
- **mode** (`'code' | 'diff'`): The view shown, when the parent owns it (with onModeChange).
- **defaultMode** (`'code' | 'diff'`, default `'code'`): The view shown first, when the component owns it.
- **onModeChange** (`(mode: 'code' | 'diff') => void`): Called when the reader switches between the code and the diff.
- **onCopy** (`(code: string) => void`): Called with the code once Copy has put it on the clipboard.
- **copyLabel** (`string`, default `'Copy'`): The copy button’s words.
- **copiedLabel** (`string`, default `'Copied'`): Its words, and what is announced, once the code is copied.
- **codeLabel** (`string`, default `'Code'`): The switch’s first view.
- **diffLabel** (`string`, default `'Diff'`): The switch’s second view.
- **defaultCopied** (`boolean`, default `false`): Opens with Copy reading Copied, held until the reader presses it again. Setting it turns the demo off.
- **autoplay** (`boolean`, default `true`): While on screen and untouched, a demo copies the code and flips to the diff and back.
- **colorScheme** (`'light' | 'dark' | 'system'`): Its colours: light, dark, or the reader’s system setting. Without it the component follows the page’s color-scheme, which is light unless the page sets one.
- **className** (`string`): Extra class for the root.
## Accessibility
- The switch is a tablist of two tabs controlling the listing, its tabpanel: Tab reaches the chosen one, the left and right arrows (and Home, End) move to the other view and focus it.
- Copy is a real button named “Copy code”; once the code is copied it is named “Copied” and a polite live region says so. The demo’s presses are never announced.
- Each line is a code element; line numbers are hidden from screen readers, and every row of the diff starts with a hidden “Added:” or “Removed:”, so the change does not rest on colour. The header’s counts read “2 added, 1 removed”.
- Focus rings are visible on the copy button and the tabs. Under reduced motion the colours change at once and the demo never plays.
## Source
### code-viewer/code-viewer.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import {
useEffect,
useEffectEvent,
useId,
useMemo,
useRef,
useState,
type KeyboardEvent as ReactKeyboardEvent,
type ReactNode,
} from 'react';
import { diff, lines, tokenize, type Token } from './highlight';
import { useAutoplay } from './use-autoplay';
import styles from './code-viewer.module.css';
/*
* Code viewer: a file in a small card, with its line numbers and syntax colours, and a Code | Diff
* switch below that shows the same file as a unified diff against its previous version.
*
* - The card has a header (an icon, the file name, a Copy button) and the listing: a grid row per
* line, a 20 px column of numbers and the code, with a hairline down the gutter. Long lines wrap.
* - The colours come from a small tokenizer in highlight.ts: keywords in the accent, calls in the
* strong ink and a little bolder, strings and numbers in orange, the rest in the quiet ink.
* - In Diff, the header trades Copy for the counts (+2 −1) and the rows follow the unified diff:
* removed lines on a red tint with a hatched edge, added ones on a green tint with a solid edge,
* and inside a changed line the changed value on a stronger chip of its colour.
* - Switching is instant, as a listing should be; only the switch's pill eases (150 ms) between
* its two buttons. Copy writes the code to the clipboard and turns into a green Copied for 1.5 s.
* - While on screen and untouched, a demo flips to the diff and back and presses Copy (without
* touching the clipboard); any input hands it to the reader.
* - Light or dark: every colour is a light-dark() token in the CSS, so the scheme is the page's
* color-scheme, or the one the colorScheme prop sets.
*/
export type CodeViewerMode = 'code' | 'diff';
const SAMPLE_BEFORE = `export async function churnBatch() {
const flavor = await getFlavor("pistachio");
const base = await dairy.fetch({ flavor });
await freezer.store(base, { temp: "-14C" });
return base.gallons;
}
`;
const SAMPLE = `export async function churnBatch() {
const flavor = await getFlavor("pistachio");
const base = await dairy.fetch({ flavor });
await freezer.store(base, { temp: "-16C" });
if (!base.approved) return null;
return base.gallons;
}
`;
/** How long Copy reads Copied. */
const COPIED_MS = 1500;
/**
* The demo's script: each step waits `wait` ms, then does its thing. A hover lights a button as
* the pointer would, just before it is pressed.
*/
type Step = {
wait: number;
hover?: 'code' | 'diff' | 'copy' | null;
mode?: CodeViewerMode;
copy?: true;
};
const SCRIPT: Step[] = [
{ wait: 2200, hover: 'copy' },
{ wait: 450, copy: true },
{ wait: 650, hover: null },
{ wait: 1700, hover: 'diff' },
{ wait: 450, mode: 'diff', hover: null },
{ wait: 3600, hover: 'code' },
{ wait: 450, mode: 'code', hover: null },
];
export type CodeViewerProps = {
/** The file as it is now: the listing, and what Copy copies. */
code?: string;
/** The file before the change; the diff compares it with `code`. null: no diff, no switch. */
previous?: string | null;
/** The name in the header. */
filename?: string;
/** The view shown, when the parent owns it. */
mode?: CodeViewerMode;
/** The view shown first, when the component owns it. */
defaultMode?: CodeViewerMode;
/** Called when the reader switches between the code and the diff. */
onModeChange?: (mode: CodeViewerMode) => void;
/** Called with the code once Copy has put it on the clipboard. */
onCopy?: (code: string) => void;
copyLabel?: string;
copiedLabel?: string;
codeLabel?: string;
diffLabel?: string;
/** Opens with Copy reading Copied, held until the reader presses it again; turns the demo off. */
defaultCopied?: boolean;
autoplay?: boolean;
colorScheme?: 'light' | 'dark' | 'system';
className?: string;
};
export function CodeViewer({
code = SAMPLE,
previous = SAMPLE_BEFORE,
filename = 'churn.ts',
mode: controlledMode,
defaultMode = 'code',
onModeChange,
onCopy,
copyLabel = 'Copy',
copiedLabel = 'Copied',
codeLabel = 'Code',
diffLabel = 'Diff',
defaultCopied = false,
autoplay = true,
colorScheme,
className,
}: CodeViewerProps) {
const id = useId();
const { ref, take, playing } = useAutoplay();
const demo = autoplay && !defaultCopied && playing;
const [ownMode, setOwnMode] = useState(defaultMode);
const [demoMode, setDemoMode] = useState(null);
const hasDiff = previous != null;
const mode: CodeViewerMode = hasDiff ? (demoMode ?? controlledMode ?? ownMode) : 'code';
const [copied, setCopied] = useState(defaultCopied);
const [announce, setAnnounce] = useState('');
const [hover, setHover] = useState(null);
const copiedTimer = useRef(0);
const tabs = useRef<(HTMLButtonElement | null)[]>([]);
const listing = useMemo(() => lines(code).map((line) => tokenize(line)), [code]);
const changes = useMemo(() => (previous != null ? diff(previous, code) : null), [previous, code]);
const flashCopied = (say: boolean) => {
setCopied(true);
if (say) setAnnounce(copiedLabel);
window.clearTimeout(copiedTimer.current);
copiedTimer.current = window.setTimeout(() => {
setCopied(false);
setAnnounce('');
}, COPIED_MS);
};
useEffect(() => () => window.clearTimeout(copiedTimer.current), []);
const choose = (next: CodeViewerMode) => {
setDemoMode(null);
if (next === mode) return;
setOwnMode(next);
onModeChange?.(next);
};
const copy = async () => {
try {
await navigator.clipboard.writeText(code);
} catch {
return;
}
flashCopied(true);
onCopy?.(code);
};
// The demo: walks its script on a timer while it plays. Its view lives apart from the
// reader's, and is dropped as soon as the reader takes over.
const step = useEffectEvent((index: number) => {
const at = SCRIPT[index];
if (at.hover !== undefined) setHover(at.hover);
if (at.mode) setDemoMode(at.mode);
if (at.copy) flashCopied(false);
});
useEffect(() => {
if (!demo || !hasDiff) {
setHover(null);
return;
}
let index = 0;
let timer = 0;
const next = () => {
timer = window.setTimeout(() => {
step(index);
index = (index + 1) % SCRIPT.length;
next();
}, SCRIPT[index].wait);
};
next();
return () => window.clearTimeout(timer);
}, [demo, hasDiff]);
// Any real input hands the demo to the reader, who keeps the view it was showing.
const handOver = () => {
take();
if (demoMode) {
setOwnMode(demoMode);
setDemoMode(null);
}
setHover(null);
};
const onTabKey = (event: ReactKeyboardEvent) => {
const order: CodeViewerMode[] = ['code', 'diff'];
const at = order.indexOf(mode);
let to = -1;
if (event.key === 'ArrowRight' || event.key === 'ArrowLeft') to = 1 - at;
else if (event.key === 'Home') to = 0;
else if (event.key === 'End') to = 1;
if (to < 0) return;
event.preventDefault();
choose(order[to]);
tabs.current[to]?.focus();
};
const rows =
mode === 'diff' && changes
? changes.rows
: listing.map((tokens, index) => ({ kind: 'same' as const, number: index + 1, tokens }));
return (