When to use
- Docs, READMEs, changelogs and AI answers: any code a reader will copy.
- One file with a name (
title), or a bare excerpt (the copy button then floats over the code and appears on hover).
When not to use
Installation
pnpm dlx shadcn add https://eased.dev/r/code-block.jsonnpx shadcn add https://eased.dev/r/code-block.jsonyarn dlx shadcn add https://eased.dev/r/code-block.jsonbunx --bun shadcn add https://eased.dev/r/code-block.jsonThe command adds Code Block, everything it builds on and Eased’s tokens to your project.
Install the dependencies
pnpm add motion shikinpm install motion shikiyarn add motion shikibun add motion shikiAdd the Eased pieces it builds on
Copy each item’s files the same way, or install them with the CLI:
Copy the source into your project
components/eased/code-block/code-block.tsxTSX "use client";import type { ReactNode } from "react";import { CopyButton } from "../_primitives/code-core/copy";import { CODE_FRAME, CODE_HEADER, LangGlyph, LangPill } from "../_primitives/code-core/code-chrome";import { CodeCollapse, CodeLines, useCodeLines } from "../_primitives/code-core/code-lines";import { langFromFilename, type CodeLang, type CodeLine } from "../_primitives/code-core/highlighter";import type { LineDecorations } from "../_primitives/code-core/lines";export type CodeBlockProps = LineDecorations & { /** The source to show and copy. One trailing newline is ignored. */ code: string; /** * tsx, ts, js, jsx, json, css, bash, html, md, python or diff (aliases like "typescript", * "sh" and "py" work). Default: from the `title`'s extension; anything else is plain text. */ lang?: CodeLang | (string & {}); /** A file name for the title bar. Without it, the copy button floats over the code. */ title?: string; /** Replace the file glyph in the title bar. */ icon?: ReactNode; /** Show the language pill in the title bar. Default true. */ showLang?: boolean; /** A line-number gutter. Default false. */ lineNumbers?: boolean; /** Number of the first line, for excerpts. Default 1. */ startLine?: number; /** * Collapse blocks longer than this many lines under a progressive blur with "Show N more * lines". Default 20; 0 never collapses. Blocks collapse only when 3 or more lines would hide. */ collapseAfter?: number; /** Start a collapsible block expanded. Default false. */ defaultExpanded?: boolean; /** Show the copy button. Default true. */ copy?: boolean; onCopy?: (code: string) => void; /** Soft-wrap long lines instead of scrolling sideways. Default false. */ wrap?: boolean; /** Pre-highlighted lines from `highlight()` (e.g. on the server), so the first paint is already coloured. */ tokens?: CodeLine[]; className?: string;};/** * Code Block: Shiki highlighting in Eased's stone (dark) and cream (light) themes, a file * title bar with a language pill, a copy button that morphs into a check while "Copied" * slides out, highlighted and focused lines, and long blocks that collapse under a * progressive blur. Grammars load on demand; the theme follows `.dark`/`data-theme`. */export function CodeBlock({ code, lang, title, icon, showLang = true, lineNumbers = false, startLine, collapseAfter = 20, defaultExpanded, copy = true, onCopy, wrap, tokens, highlight, focus, added, removed, className = "",}: CodeBlockProps) { const language = lang ?? langFromFilename(title) ?? undefined; const { lines } = useCodeLines(code, language, tokens); const label = title ? `Copy ${title}` : "Copy code"; return ( <figure className={`m-0 ${CODE_FRAME} ${className}`}> {title !== undefined && ( <figcaption className={CODE_HEADER}> {icon ?? <LangGlyph lang={language} />} <span className="min-w-0 flex-1 truncate font-mono text-ui-sm text-text-secondary">{title}</span> {showLang && <LangPill lang={language} />} {copy && <CopyButton text={code} label={label} onCopy={onCopy} />} </figcaption> )} <CodeCollapse lines={lines.length} collapseAfter={collapseAfter} defaultExpanded={defaultExpanded}> <CodeLines lines={lines} lineNumbers={lineNumbers} startLine={startLine} wrap={wrap} label={title} highlight={highlight} focus={focus} added={added} removed={removed} className={title === undefined && copy ? "[&_[data-line]:first-child]:pr-12" : ""} /> </CodeCollapse> {title === undefined && copy && ( // Pointer devices reveal it on hover or focus; touch screens always show it. <div className="absolute top-1.5 right-1.5 z-10 rounded-control-sm bg-surface-sunken transition-opacity duration-150 ease-standard pointer-fine:opacity-0 pointer-fine:group-hover:opacity-100 pointer-fine:focus-within:opacity-100"> <CopyButton text={code} label={label} showLabel={false} onCopy={onCopy} /> </div> )} </figure> );}Keep the folder layout
The files import each other by relative path (
../lib/motion), so keep each one at the path shown, undercomponents/eased/.
Usage
import { CodeBlock } from "@/components/eased/code-block/code-block";<CodeBlock title="use-debounced-value.ts" code={source} lineNumbers highlight="7-8, 16-17" />Examples
Pre-highlighted on the server
Pass tokens from highlight() so the first paint is already coloured, with no plain-text frame.
import { CodeBlock } from "@/components/eased/code-block/code-block";import { highlight } from "@/components/eased/_primitives/code-core/highlighter";export default async function Page() { const tokens = await highlight(source, "tsx"); return <CodeBlock title="button.tsx" code={source} tokens={tokens} />;}A diff
added and removed tint whole lines and add a + / − column.
<CodeBlock title="next.config.ts" code={config} added="4-5" removed={3}/>Focused lines in an excerpt
focus dims every other line until the pointer is over the block; startLine numbers an excerpt from where it sits in the file.
<CodeBlock title="checkout.ts" code={excerpt} lineNumbers startLine={41} focus="44-46" collapseAfter={0} />API reference
CodeBlock
| Prop | Type | Default | Description |
|---|---|---|---|
code | string | The source to show and copy. One trailing newline is ignored. | |
lang | CodeLang | string | from title | tsx, ts, js, jsx, json, css, bash, html, md, python, diff (aliases such as typescript, sh, py work). Anything else renders as plain text. |
title | string | File name for the title bar. Without it, the copy button floats over the code. | |
icon | ReactNode | file glyph | Replaces the glyph before the title. Shell languages get a prompt glyph. |
showLang | boolean | true | The language pill (hidden under 320px of block width). |
lineNumbers | boolean | false | A tabular-nums slashed-zero gutter that is never selected or copied. |
startLine | number | 1 | First line number, for excerpts. |
highlight | LineRange | Lines to tint: "3-5, 9", 4, or [1, [6, 8]]. | |
focus | LineRange | Lines to keep sharp; the rest dim to 40% until hover. | |
added / removed | LineRange | Diff lines, tinted green or red with a + / − marker. | |
collapseAfter | number | 20 | Collapse longer blocks; only when 3 or more lines would hide. 0 never collapses. |
defaultExpanded | boolean | false | Start a collapsible block open. |
copy | boolean | true | Show the copy button. |
onCopy | (code: string) => void | After a successful copy. | |
wrap | boolean | false | Soft-wrap instead of scrolling sideways. |
tokens | CodeLine[] | Lines from highlight(), to skip client highlighting. | |
className | string | "" | Appended to the <figure>'s classes. |
highlight(code, lang) comes from _primitives/code-core/highlighter and returns Promise<CodeLine[]>, plain serialisable data a server component can hand to the block.
Keyboard
| Key | Action |
|---|---|
Tab | Moves through the copy button, the code (only when it scrolls sideways) and "Show more". |
← / → | Scroll the focused code sideways. |
Enter / Space | Copies the code, or expands and collapses a long block. |
Accessibility
- A
<figure>with the title as its<figcaption>. The copy button is named "Copy use-debounced-value.ts" (or "Copy code" without a title), and a polite status line announces "Copied". - Code that overflows sideways becomes a focusable
regionnamed by the title, so keyboard users can scroll it. - Added and removed lines carry hidden "(added)" and "(removed)" text, so the diff is not colour alone. Line numbers and diff markers are hidden from screen readers.
- "Show more" sets
aria-expandedandaria-controls. Collapsed lines are clipped, not removed, and the copy button always copies the whole source. - The copy button has a 44px hit area. Without a title it appears on hover or focus with a mouse, and is always visible on touch screens.
Motion
Copying lifts and blurs the two sheets away while a check draws itself in on the snappy spring and "Copied" slides out beside it; after 1.6s the copy icon comes back. Expanding a long block springs its height open on the smooth spring (no overshoot) while the blur and tint fade in 100ms; collapsing brings them back over 150ms, the chevron turns on snappy, and a block whose top is off-screen scrolls back into view. Blocks with more than 480px of hidden code open in place, without the height spring, so the page does not lurch. Reduced motion: the copy icon cross-fades, the height snaps and the blur fades in 100ms.
Notes for AI
Use CodeBlock for one file or one excerpt. Set title to the file name (it also picks the grammar), highlight for the lines the surrounding text talks about, and lineNumbers when the text cites line numbers. In a server component, pass tokens from highlight() so there is no plain-text first paint.
Do not wrap it in another copy button, a <pre>, or a card with its own border: it draws its own frame. Grammars load on demand through one shared Shiki instance (JavaScript regex engine, no WASM), and token colours use CSS light-dark(), so a theme switch never re-highlights; the block follows .dark or data-theme="dark" on an ancestor.
Related components
- Package Manager Code Tabs: several files, or one command per package manager, in one block.
- Copyable Command Snippet: a one-line command with a
$prompt. - Heading Typography Scale