--- title: "Code block" description: "Lines of code to read, compare and copy, in the code face, scrolling inside itself or wrapping, with an optional header, line numbers, marked lines, a prompt and a copy button. Given the code and its language, it highlights the code by itself." url: "https://tanrei.chnotchy.com/components/code-block/" last_updated: 2026-10-23T21:17:12.000Z --- # Code block > Lines of code to read, compare and copy, in the code face, scrolling inside itself or wrapping, with an optional header, line numbers, marked lines, a prompt and a copy button. Given the code and its language, it highlights the code by itself. ## Overview A code block shows code that people read, compare and copy. A name or a command inside a sentence is [Inline code](https://tanrei.chnotchy.com/components/inline-code/). **The code block highlights code by itself.** Give it the code and its `language`, and it colors the code from tokens: no highlighter to install, no theme and no stylesheet to write. So code follows the scheme, the contrast level and the design system like everything else on the page. Highlighting is color and weight and nothing else: the characters, the lines, what is selected, what is copied and what a screen reader reads are the same with it and without it. ### Usage On the web the code stays in your document, as an ordinary `
`. It is there without script: for a reader whose script failed, for search engines, for find-in-page. The element draws the frame around it. Load `@tanrei/web/code.css` to give a block its fill, corners, padding and face before the element is defined.

SwiftUI, Compose, Flutter and React Native are planned: the names beside each platform at the top of this page are the ones the spec gives them, and nothing ships there yet.

**Web**

```html




  
const sizes = ['small', 'medium', 'large'];





  
…




  
npm install @tanrei/web




```

**React**

```tsx
import { CodeBlock } from '@tanrei/react';
import '@tanrei/web/code.css';

{/* The element lays the code out in lines, so let it own the code: pass the text. */}

```

`language` is an identifier (`tsx`, `css`, `sh`): it is what the block highlights by, and it is not drawn. The words in the header are `language-label`. A block built by script sets the `code` property instead of holding a `
`, and the element writes the `
` itself.

## Specs

**Two looks.** `filled` is a quiet fill, for code on a page. `outlined` has no fill inside one hairline, for code inside a card or a panel that is already filled.

**The body.** A line is never broken by default. A line that does not fit scrolls inside the block, and the page never scrolls sideways. `wrap` breaks lines instead, and a continued row starts under the code, not under the numbers. `max-lines` caps the height in lines, and the rest scrolls inside the block.

**The copy button** is always drawn, never only on hover. It never covers code that cannot be moved clear of it: a scrolling body gains that much room at its end, and wrapped rows stop before its column. It copies the code as plain text, without line numbers, the prompt, the signs or the removed lines. A selection made by hand copies exactly the characters selected.

**Marked lines** are never marked by color alone.

| Mark | Bar at the left edge | Band | Sign | Read before the line |
| --- | --- | --- | --- | --- |
| Highlighted | yes | yes |  | `highlighted-label` |
| Added | yes | faint green | + | `added-label` |
| Removed | yes | faint red | − | `removed-label` |

Line lists are numbers and ranges separated by commas (`"3, 7-9"`). They count as the numbers the reader sees, from `start-line`.

**Right to left.** Code is always left to right: lines, numbers and the start of scrolling are at the left in every layout. Only the frame mirrors, so the title moves to the right and the copy button to the left.

- Category: Containment
- Level: base
- Listing: default
- Page: https://tanrei.chnotchy.com/components/code-block/
- Spec: https://github.com/chnotchy/tanrei/blob/main/specs/code-block.spec.json

### Availability

| Design system | Has it | Notes |
| --- | --- | --- |
| Tanrei (`tanrei`) | Yes | — |
| Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — |
| M3 Expressive-like (Material 3 Expressive-inspired) (`m3-expressive-like`) | Yes | — |
| M3-like (Material 3-inspired) (`m3-like`) | Yes | — |

### Platforms

- Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/code-block`).
- React: `CodeBlock` from `@tanrei/react`.

| Platform | Name | Status |
| --- | --- | --- |
| Web | `tanrei-code-block` | lagging |
| SwiftUI | `TanreiCodeBlock` | planned |
| Jetpack Compose | `TanreiCodeBlock` | planned |
| Flutter | `TanreiCodeBlock` | planned |
| React Native | `CodeBlock` | planned |

Names a platform gives in its own idiom:

| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
| --- | --- | --- | --- | --- | --- |
| `title` (prop) | `headline` | `title` | `title` | `title` | `title` |
| `highlight` (prop) | `highlight` | `highlightsSyntax` | `highlightSyntax` | `highlightSyntax` | `highlight` |
| `wrap` (prop) | `wrap` | `wrapsLines` | `softWrap` | `softWrap` | `wrap` |
| `lineNumbers` (prop) | `lineNumbers` | `showsLineNumbers` | `showLineNumbers` | `showLineNumbers` | `showLineNumbers` |
| `maxLines` (prop) | `maxLines` | `lineLimit` | `maxLines` | `maxLines` | `maxLines` |
| `copy` (prop) | `copy` | `showsCopyButton` | `showCopyButton` | `showCopyButton` | `copy` |
| `copied` (event) | `copied` | `onCopied` | `onCopied` | `onCopied` | `onCopied` |
| `copyFailed` (event) | `copyfailed` | `onCopyFailed` | `onCopyFailed` | `onCopyFailed` | `onCopyFailed` |

Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal.

### Anatomy

- `container`: The block: a quiet fill (filled) or no fill inside one hairline (outlined), with small corners. As wide as its layout gives it.
- `outline` (optional): The outlined look's edge: one hairline inside the container.
- `header` (optional): A row above the code that holds the title, the language and, where there is one, the copy button. It has no fill and no line of its own: it is the top of the same container.
- `title` (optional): What the code is: a file name or a few words. At the start of the header.
- `language` (optional): The language label: the language the code is in, in the product's words. At the end of the header, before the copy button.
- `copy-button` (optional): A Copy button (its own component) that copies the code: in the header where there is one, at the block's top end corner otherwise.
- `body`: The part that holds the lines and scrolls inside the container when they do not fit.
- `code`: The code: its lines, each on one line of the code's text style, each run in the color and weight of its syntax role where the code is highlighted.
- `line-number` (optional): A line's number, in the gutter at the left of the code. Drawn, not text.
- `mark` (optional): A bar at the left edge of a highlighted, an added or a removed line.
- `sign` (optional): A plus or a minus in the gutter of an added or a removed line. Drawn, not text.
- `prompt` (optional): A prompt drawn before each line of a block of commands. Drawn, not text.

### Props

| Prop | Type | Default | Web attribute | Description |
| --- | --- | --- | --- | --- |
| `code` | `string` | `""` | `code` | The code as plain text, lines separated by line breaks. It is what is drawn, what is highlighted and what is copied. Ignored where runs are given: their texts, joined, are the code. |
| `variant` | `enum`: `filled`, `outlined` | `"filled"` | `variant` | filled: a quiet fill, for code on a page. outlined: no fill inside one hairline, for code inside a container that is already filled (a card, a panel). A design system may add values. |
| `size` | `enum`: `small`, `medium` | `"medium"` | `size` | medium sets the code in the code role (13), for a page and a panel. small sets it in the small code role (12) with less padding, for dense interfaces. A design system may add values. |
| `title` | `string` | `""` | — | A file name or a few words that say what the code is ("button.tsx", "Response"). Drawn in the header and used as the block's accessible name. |
| `language` | `string` | `""` | `language` | The language the code is written in, as an identifier ("tsx", "css", "swift", "sh"), read without regard to case. It is what the block highlights by (COD-19, COD-27); it is not drawn. Empty, "text" and "plain" mean code that has no syntax; a language the highlighter does not know is drawn plain. |
| `languageLabel` | `string` | `""` | `language-label` | The language in the product's words ("TypeScript", "Shell"), drawn in the header. A label only: the block does not highlight by it, and draws no label of its own for language. |
| `highlight` | `boolean` | `true` | `highlight` | True: the block highlights the code by itself where it can (COD-19). False: it never does, whatever language says; runs the product gives are still drawn in their colors. |
| `label` | `string` | `""` | `label` | The block's accessible name where it has no title ("Example", "Request body"), in the product's language. Not drawn. A block that can scroll needs a title or a label. |
| `wrap` | `boolean` | `false` | `wrap` | False: a line is never broken, and lines that do not fit scroll sideways inside the block. True: a line that does not fit continues on the next row, and nothing scrolls sideways. |
| `lineNumbers` | `boolean` | `false` | `line-numbers` | Draws each line's number in a gutter at the left of the code. |
| `startLine` | `number` | `1` | `start-line` | The number of the first line: an excerpt of a file keeps the file's numbers. A whole number of 1 or more. |
| `highlightedLines` | `string` | `""` | `highlighted-lines` | The lines the text around the block talks about, by number, as numbers and ranges separated by commas ("3, 7-9"). Numbers are the ones lineNumbers would draw (they count from startLine). |
| `addedLines` | `string` | `""` | `added-lines` | The lines a change adds, written as highlightedLines is. |
| `removedLines` | `string` | `""` | `removed-lines` | The lines a change takes away, written as highlightedLines is. They are drawn and are left out of what the copy button copies. |
| `highlightedLabel` | `string` | `""` | `highlighted-label` | What assistive technology reads before a highlighted line ("Highlighted"), in the product's language. Required while highlightedLines names a line. |
| `addedLabel` | `string` | `""` | `added-label` | What assistive technology reads before an added line ("Added"). Required while addedLines names a line. |
| `removedLabel` | `string` | `""` | `removed-label` | What assistive technology reads before a removed line ("Removed"). Required while removedLines names a line. |
| `prompt` | `string` | `""` | `prompt` | A prompt ("$", ">") drawn before every line that is not empty, for a block of commands to type. It is not part of the code: it is not selected, not copied and not read. |
| `maxLines` | `number` | — | `max-lines` | The most lines shown at once; more than that scroll up and down inside the block. Null shows every line. |
| `copy` | `boolean` | `false` | `copy` | Draws a copy button that copies the code. |
| `copyLabel` | `string` | `""` | `copy-label` | The copy button's accessible name ("Copy"), in the product's language. Required while copy is true. |
| `copiedLabel` | `string` | `""` | `copied-label` | What the copy button announces when the code has been copied ("Copied"). Required while copy is true. |
| `copyFailedLabel` | `string` | `""` | `copy-failed-label` | What the copy button announces when the platform refuses the copy ("Could not copy"). Required while copy is true. |

### Events

| Event | Description |
| --- | --- |
| `copied` | The code was copied by the block's copy button; carries the text that was copied. |
| `copyFailed` | The platform refused the copy asked for by the block's copy button. |

### Item: `run`

A piece of the code that is one kind of thing — a comment, a keyword, a string, a function's name — as the block's highlighter found it, or as the product names it where the product gives the runs. The runs' texts, in order, are the code.

Names: Web `span`, SwiftUI `TanreiCodeRun`, Jetpack Compose `TanreiCodeRun`, Flutter `TanreiCodeRun`, React Native `CodeRun`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | `""` | The run's characters, exactly as in the code. It may hold line breaks: a run may span lines. |
| `syntax` | `enum`: `plain`, `comment`, `keyword`, `string`, `constant`, `function`, `type`, `tag`, `property`, `punctuation` | `"plain"` | What the run is. comment: a comment or a documentation comment. keyword: one of the language's own words (a keyword, a storage or modifier word, an at-rule, an annotation, an operator written as a word). string: text written in the code (a string, a character, a regular expression, the value of a markup attribute). constant: a value that is not text (a number, a boolean or null, a named constant, a unit, a color value, an escape inside a string). function: the name of a function or a method, declared or called. type: the name of a type (a class, a structure, an interface, an enumeration, a built-in type, a namespace). tag: what markup and style sheets address (an element's name, a component's name in markup, a selector). property: a name that belongs to something (a property, a key, a markup attribute, a style declaration's property, a command's option). punctuation: brackets, separators and the delimiters of markup. plain: none of these — variables, parameters, operators written as signs, text between tags. The values are those of the token axis comp.code-block.syntax and plain; a design system may add values to that axis. |

### States

`enabled`, `focused`

### Accessibility

- Role: `group`
- Labeling: The block is a group named by title, or by label where it has no title; inside it the code is text with the role of code where the platform has one. The copy button is named by copyLabel. Line numbers, prompts, signs and bars are hidden; a marked line is preceded by its label in words (highlightedLabel, addedLabel, removedLabel).
- Minimum target size: yes

| Keys | Action |
| --- | --- |
| Tab | Moves focus to the copy button where there is one, then to the body while it can scroll. A block that neither scrolls nor copies is not a stop. |
| Arrow keys, Page Up, Page Down, Home, End | Scroll the focused body, as the platform scrolls any region. |
| Enter or Space | On the copy button: copies the code (CPY-2). |

- The only target is the copy button, whose hit area meets the minimum target by its own spec (CPY-1, BTN-5) though it is drawn 32 high. The body is scrolled, not pressed.
- A body that scrolls must be reachable by keyboard (WCAG 2.1.1) and so is a focus stop with a visible focus indicator (COD-7); one that does not scroll is not, so a page of short examples adds no stops. A group, not a landmark: a page may hold hundreds of blocks.
- Reflow (WCAG 1.4.10): code is two-dimensional content, so sideways scrolling inside the block is allowed, and the page itself never scrolls sideways (COD-4, COD-24). wrap is for a product that prefers no sideways scrolling at all.
- A marked line is never marked by color alone (WCAG 1.4.1): a highlighted line has a bar and a band and its label; an added or a removed line has a bar, a plus or a minus and its label (COD-15, COD-16). Syntax colors carry no meaning a reader needs: the same code drawn plain says the same thing, a role is never exposed (COD-22), and keywords are also told by weight. With a red-green color vision deficiency some of the default system's six hues draw together — the green of a string and the red of a tag's name first — beside the neutral tones and the keyword's weight; nothing is lost but a distinction between kinds of words.
- Contrast: the code, the line numbers, the prompt and the signs are roles the token invariants hold at 4.5:1 on every surface (7:1 in the high-contrast schemes). Every syntax color is held by the build at the same ratios against the block's fill, against the band of a highlighted line and against every surface role, which is what an outlined block may stand on, in each system. The bars are primary, success and error, held at the same ratios, above the 3:1 a mark needs. The outlined look's edge is decorative.
- An outlined block is read on whatever it is placed on. On a surface that is correct. On a colored container (a callout) the syntax colors are not paired with that container: use filled there, which brings its own surface.
- The copy button is always drawn (COD-9): one that appears only under a pointer cannot be found by touch, and one that appears on focus moves under a keyboard user. Its confirmation is announced by the Copy button's own live region (CPY-5).
- Highlighting adds nothing for assistive technology and takes nothing away: the code is the same text before and after the colors arrive, no live region speaks of them, and the body's scroll position, the selection and the focus are kept (COD-28). Colors arrive in one frame, without a motion, so nothing flashes more than once.
- Screen readers read code as text, symbol by symbol as the person's settings say. The code block adds no line numbers or roles to that reading; the marks' labels are the only words it adds.
- Code is not translated and not spell-checked (COD-2); comments in it are the author's language and are read with the page's voice unless the product marks their language.

### Behaviour

Requirements in EARS form, each with its stable id.

- **COD-1** THE code block SHALL draw a container filled with the container color of its variant (comp.code-block.filled.container.color for filled, comp.code-block.outlined.container.color for outlined), with corners comp.code-block.container.shape eased by sys.shape.corner-smoothing and no elevation, as wide as its layout gives it and never wider, and SHALL bring no space outside itself: the layout it sits in spaces it (PRS-15). WHILE variant is outlined it SHALL draw an edge comp.code-block.outline.width wide in comp.code-block.outline.color inside the container's size, following its corners; WHILE variant is filled it SHALL draw no edge.
- **COD-2** THE code block SHALL set the code in the text style of its size, taken whole (comp.code-block.code.typescale.medium for medium, and so on), in comp.code-block.code.color where a run names no syntax role, every line of the code on one line of that style; it SHALL draw the characters as given — every space kept, a tab advancing to the next multiple of comp.code-block.code.tab-size columns, nothing hyphenated, transformed, translated or spell-checked — and SHALL draw no empty last line for one line break at the end of the code.
- **COD-3** THE code block SHALL pad the code by the block padding of its size above the first line and below the last (comp.code-block.container.padding-block.medium for medium, and so on) and by the inline padding of its size (comp.code-block.container.padding-inline.medium for medium, and so on) before the start of the lines, or of the gutter where there is one (COD-13), and after the end of the longest line.
- **COD-4** WHILE wrap is false THE code block SHALL NOT break a line; WHEN a line is wider than the body THE body SHALL scroll sideways inside the container, by pointer, touch, the wheel and the keyboard (COD-7), the page SHALL NOT scroll sideways for it, and the padding after the longest line SHALL scroll with the code, so that its last character can be brought clear of the container's edge. The header and the copy button SHALL NOT scroll with the code. A gesture or a wheel movement up or down over a body that cannot scroll that way SHALL scroll the page.
- **COD-5** WHILE wrap is true THE code block SHALL continue a line that does not fit on following rows: it breaks first at the spaces of the line and, where a part with no space is wider than the row, between any two characters; a following row SHALL begin at the column where the line's code begins (after the gutter and the prompt), draw no mark of its own and add no character; the body SHALL NOT scroll sideways; and what is selected or copied SHALL hold the line breaks of the code alone.
- **COD-6** WHILE maxLines is a number and the code has more lines than that THE body SHALL be maxLines lines of the code's text style high plus its paddings and SHALL scroll up and down inside the container; the header and the copy button SHALL NOT scroll with it. WHILE maxLines is null, or the code has no more lines than it, THE code block SHALL be as tall as its lines.
- **COD-7** WHILE the body can scroll, sideways or up and down, THE body SHALL be one stop in the focus order after the copy button, SHALL scroll by the arrow keys, Page Up, Page Down, Home and End as its platform scrolls any region, and, WHEN it has keyboard focus, SHALL show the focus indicator inside the container's edge, its corners following comp.code-block.container.shape, as sys.behavior.focus-style names (ring or glow), without animation; focus gained by pointer or touch SHALL NOT show it; a platform that cannot draw a choice SHALL fall back to the first value and state that in its README. WHILE the body cannot scroll it SHALL NOT be a stop in the focus order.
- **COD-8** WHILE title or languageLabel is not empty THE code block SHALL draw a header above the code, in the same container, with no fill and no line of its own: the title at the start, in comp.code-block.title.typescale and comp.code-block.title.color, on one line, laid out as text of its own direction and cut with an ellipsis at the end of that direction when it does not fit; the language label (languageLabel) at the end, before the copy button where there is one, in comp.code-block.language.typescale and comp.code-block.language.color, never cut; its items comp.code-block.header.gap apart. The header's row SHALL begin comp.code-block.copy-button.inset from the container's top edge, be as tall as the copy button where there is one and as one line of the title's text style otherwise, with its items centred on it; the title SHALL begin at the inline padding of COD-3; and the code SHALL begin comp.code-block.header.padding-block-end below the row in place of the block padding of COD-3.
- **COD-9** WHILE copy is true THE code block SHALL place a Copy button (CPY) — icon-only, of the text variant and the small size, named by copyLabel, with copiedLabel and copyFailedLabel as its two announcements — comp.code-block.copy-button.inset from the container's top edge and from its end edge: at the end of the header where there is one, and over the top end corner of the body otherwise. THE copy button SHALL be drawn whenever the block is, never only under a pointer or on focus; SHALL come before the body in the focus order and in reading order; and SHALL keep its place and size in every form it takes (CPY-7). THE container SHALL be at least as tall as the copy button plus twice that inset.
- **COD-10** WHILE copy is true and there is no header THE code block SHALL keep code readable beside the button: WHILE wrap is false the padding after the longest line (COD-3, COD-4) SHALL be widened by the button's width and that inset, so that any line's end can be scrolled clear of the button; WHILE wrap is true every row SHALL end before the button's column. THE copy button SHALL stand on a patch of the container's own color where code can pass under it.
- **COD-11** THE copy button of COD-9 SHALL copy the code as plain text: its lines in order, joined by line breaks, without line numbers, prompts, signs or labels, without the lines removedLines names, and with no line break that wrapping added. WHEN the Copy button emits copied or copyFailed THE code block SHALL emit its own event of that name, copied carrying the text.
- **COD-12** WHEN a person selects in the body THE code block SHALL select characters of the code alone: line numbers, prompts, signs, bars and the labels of COD-15 and COD-16 SHALL NOT be selectable and SHALL NOT be part of what a copied selection holds; a copied selection SHALL hold the selected characters, removed lines included where they were selected, with the code's own line breaks.
- **COD-13** WHILE lineNumbers is true THE code block SHALL draw before each line its number, counting from startLine, in the code's text style with digits of one width, in comp.code-block.line-number.color, right-aligned in a column as wide as the widest number drawn; a line that wraps SHALL carry its number on its first row only. The gutter — from the left: the bar's column (COD-15), the numbers, the signs (COD-16) — SHALL stand comp.code-block.line-number.gap from the start of the code, SHALL stay in view on the container's color while the code scrolls sideways under it, and SHALL be kept from assistive technology.
- **COD-14** THE code block SHALL read highlightedLines, addedLines and removedLines as numbers and ranges separated by commas, each number being a line's number as COD-13 counts it whether or not numbers are drawn; it SHALL ignore a number outside the code and an entry it cannot read, and in debug builds report it. A line named as both added and removed SHALL be drawn removed, and in debug builds reported; a line named as highlighted and as added or removed SHALL be drawn as both.
- **COD-15** WHILE a line is highlighted THE code block SHALL draw behind all of its rows a band of comp.code-block.line.highlighted.container.color from the container's left edge to its right, and at the container's left edge a bar comp.code-block.line.mark.width wide in comp.code-block.line.highlighted.mark.color as tall as the line; and SHALL expose highlightedLabel to assistive technology before the line's text, without drawing it. The line's code SHALL keep its colors.
- **COD-16** WHILE a line is added or removed THE code block SHALL draw at the container's left edge a bar comp.code-block.line.mark.width wide, as tall as the line, and in the gutter after the numbers a sign in the code's text style — a plus (+) for an added line, a minus (−) for a removed one — both in comp.code-block.line.added.mark.color for an added line and comp.code-block.line.removed.mark.color for a removed one; and SHALL expose addedLabel or removedLabel before the line's text, without drawing it. THE code block SHALL also draw behind the line, from the container's left edge to its right and under the bar, the sign and the code, a band in comp.code-block.line.added.container.color for an added line and comp.code-block.line.removed.container.color for a removed one, so that a reader scanning the block tells added from removed lines whatever the colors of their code. The line's code SHALL keep its syntax colors, which are held on these bands at the contrast of code text, and SHALL NOT be struck through: the sign and the label say what the line is, never the color alone.
- **COD-17** WHILE prompt is not empty THE code block SHALL draw the prompt and one space of the code's text style before the first row of every line that is not empty, in comp.code-block.prompt.color, after the gutter; following rows of a wrapped line SHALL begin under the code, not under the prompt; the prompt SHALL be kept from assistive technology and is not code (COD-11, COD-12).
- **COD-18** THE code block SHALL draw each run in the color of its syntax role — comp.code-block.syntax.color.comment for comment, comp.code-block.syntax.color.keyword for keyword, comp.code-block.syntax.color.string for string, comp.code-block.syntax.color.constant for constant, comp.code-block.syntax.color.function for function, comp.code-block.syntax.color.type for type, comp.code-block.syntax.color.tag for tag, comp.code-block.syntax.color.property for property, comp.code-block.syntax.color.punctuation for punctuation, and comp.code-block.code.color for plain — and with the weight of the code's text style plus the emphasis of its role (comp.code-block.syntax.emphasis.keyword for keyword, and so on; none for plain), whether the block's highlighter found the run (COD-19) or the product gave it (COD-29). A syntax role SHALL change a run's color and weight alone — never its size, family, spacing, slant, decoration or background — so that highlighted code and the same code drawn plain have the same lines, columns and size. A role a design system added to the axis SHALL be drawn from that role's two tokens in the same way.
- **COD-19** WHILE highlight is true, the product gives no runs (COD-29), language names a language the highlighter knows (COD-27) and the code is no longer than comp.code-block.syntax.max-length characters THE code block SHALL highlight the code by itself: its highlighter reads the code as that language and names the syntax role of every run, and the block draws the runs as COD-18 says. Highlighting SHALL change nothing but colors and weights: the code's characters, its lines, what is selected, what is copied (COD-11, COD-12) and what assistive technology reads (COD-22) are those of the code as given. In every other case THE code block SHALL draw all of the code in comp.code-block.code.color. WHEN a run names a syntax role the active design system does not have THE code block SHALL draw that run as plain, and in debug builds report the unknown role.
- **COD-20** THE code block SHALL lay out the body left to right in every layout direction (PRS-26): lines begin at the left, the gutter, the bars and the bands' start are at the left, the prompt is at the left of its line, and sideways scrolling starts at the left. WHERE the layout direction is right-to-left THE code block SHALL mirror the frame alone: the title at the right of the header, the language and the copy button at the left, and the copy button of a block without a header at the top left corner; the paddings of COD-10 SHALL then apply at the button's side. A comment written in a right-to-left script SHALL be laid out by the bidirectional algorithm inside its left-to-right line.
- **COD-21** THE code block SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the code block is shown THE code block SHALL draw itself for the new direction at once, without a motion of its own, keeping its scroll offsets, its selection and its focus.
- **COD-22** THE code block SHALL expose its code to assistive technology as text in reading order, line after line, with the role of code where the platform has one, inside a group named by title where it is not empty and by label otherwise; the language label SHALL be read as text of the header and language itself SHALL NOT be read; a syntax role SHALL NOT be exposed, and colors arriving or changing (COD-28, COD-30) SHALL NOT be announced; and WHEN code, the runs or a marked line changes THE code block SHALL draw and expose the new content at once, without a motion, SHALL NOT announce the change, and SHALL keep the body's scroll offsets where the content still reaches them.
- **COD-23** WHERE the platform draws with a person's own forced colors THE code block SHALL draw an edge comp.code-block.outline.width wide in the platform's text color inside its container in every variant; its code in the platform's text color whatever syntax role a run names, every run keeping the weight of its role; line numbers, prompts, signs and bars in that text color; and no band: a highlighted line is then marked by its bar, and an added or a removed line by its bar and its sign.
- **COD-24** WHILE the text size is enlarged THE code block SHALL grow its lines, its gutter and its header with the text, keeping its paddings and its corners, and the copy button SHALL keep the size and the target of its own spec; at twice the text size in a container 320 wide the body SHALL scroll inside the container (COD-4) or wrap (COD-5), the title SHALL be cut as COD-8 says, and the page SHALL NOT scroll sideways.
- **COD-25** IF code is empty and no runs are given THE code block SHALL draw nothing, take no space and expose nothing, and in debug builds report that a code block has no code. WHILE copy is true and copyLabel, copiedLabel or copyFailedLabel is empty, WHILE a line is marked and the label of its mark (highlightedLabel, addedLabel, removedLabel) is empty, and WHILE the body can scroll and both title and label are empty THE code block SHALL still draw, and in debug builds report what is missing. WHEN variant or size names a value the active design system does not have THE code block SHALL render with the default value, and in debug builds report the unknown value; a startLine below 1 or not whole SHALL be taken as 1 and a maxLines below 1 as null.
- **COD-26** THE code block SHALL NOT take a press itself and has no hovered, pressed, selected or disabled state: it draws no state layer and no ripple. What is pressed inside it is its Copy button, which answers a press as its own spec says (CPY-12 to CPY-14).
- **COD-27** THE code block SHALL read language as an identifier, without regard to case and to space around it, and match it against the names and the other names of the languages its highlighter knows. THE highlighter the code block brings SHALL know these languages: markup (html, xml, svg), css, javascript (js, mjs, cjs, jsx), typescript (ts, tsx), json (jsonc), shell (sh, bash, zsh), swift, kotlin (kt) and dart; a product SHALL be able to add a language, to replace one, and to replace the highlighter whole, once for all the code blocks it draws. WHILE language is empty, "text", "plain" or "plaintext" THE code block SHALL draw the code plain and report nothing; WHILE language names a language the highlighter does not know it SHALL draw the code plain, and in debug builds report the unknown language once for each name. THE code block SHALL NOT guess a language from the code, from title or from languageLabel.
- **COD-28** THE code block SHALL draw the code at once, plain, without waiting for its highlighter: no part of the highlighter is loaded for a block that will not use it, and a block that waits for it is complete in every other respect. WHEN the runs are ready THE code block SHALL draw every color and weight in one frame, without a motion and without a fade, moving no line and no character, changing the size of nothing, and keeping the body's scroll offsets, the selection and the focus. WHERE the runs are already with the code when the block is first drawn (code highlighted where the page was made) THE code block SHALL draw them in its first frame.
- **COD-29** WHERE the product gives runs THE code block SHALL take the runs' texts, joined in order, as the code, SHALL draw them as COD-18 says, and SHALL NOT highlight the code itself, whatever language and highlight say: code that was highlighted where the page was made, or by a highlighter the product chose for one block, is drawn as it was given. Code given with the statement that it has been highlighted and has no run with a role SHALL be drawn plain in the same way.
- **COD-30** WHEN code, language or highlight changes while the block is shown THE code block SHALL draw the new code at once and highlight it again; a result for code that is no longer the code shown SHALL be dropped, never drawn. WHERE its highlighter can answer in the same frame THE code block SHALL draw the new code with its colors in that frame. Otherwise the lines before the first line that changed SHALL keep their colors until the new runs are ready, and the lines from there on SHALL be drawn plain until then, so that code that grows at its end does not lose and regain its colors with every piece.
- **COD-31** WHILE the code is longer than comp.code-block.syntax.max-length characters THE code block SHALL draw all of it plain — never a part of it highlighted — and in debug builds report that the code is too long to highlight. Runs the product gives are drawn whatever their length.
- **COD-32** IF the highlighter cannot be loaded, fails while it reads the code, or answers with runs whose texts do not join to the code exactly THEN THE code block SHALL draw the code plain, SHALL keep everything else it draws and does — the header, the copy button, the lines, the marks, scrolling — and in debug builds report what failed. A failure in one block SHALL NOT change another block.
- **COD-33** WHILE addedLines or removedLines names a line THE code block SHALL highlight the code as the two texts it holds: the lines that are not removed, in order, are read as one text — the code as it is after the change, which is what is copied (COD-11) — and color the lines that are not removed; the lines that are not added, in order, are read as another — the code as it was before — and color the removed lines. A highlighted line and an added or a removed line SHALL keep the colors of their runs over the band and beside the bar and the sign (COD-15, COD-16).
- **COD-34** WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE code block SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on its body, which SHALL be a group WHILE it has a name: its title or label, or one given so — an id reference by the elements it names in the host's tree or a tree around it, a description after its own. WHILE the title or label is not empty it is the body's name, over a name given so; a name given so SHALL count as the body's name for the report of COD-25. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE code block SHALL take it off that element.

### Tokens

As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.code-block.…` → `--tanrei-comp-code-block-…`).

#### `tanrei.comp.code-block`

| Token | Type | Value |
| --- | --- | --- |
| `comp.code-block.filled.container.color` | `color` | `{tanrei.sys.color.surface-container}` |
| `comp.code-block.outlined.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` |
| `comp.code-block.container.shape` | `dimension` | `{tanrei.sys.shape.corner.small}` |
| `comp.code-block.container.padding-block.small` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.code-block.container.padding-block.medium` | `dimension` | `{tanrei.sys.space.space150}` |
| `comp.code-block.container.padding-inline.small` | `dimension` | `{tanrei.sys.space.space150}` |
| `comp.code-block.container.padding-inline.medium` | `dimension` | `{tanrei.sys.space.space200}` |
| `comp.code-block.outline.color` | `color` | `{tanrei.sys.color.outline-variant}` |
| `comp.code-block.outline.width` | `dimension` | `{tanrei.sys.border.hairline}` |
| `comp.code-block.code.typescale.small` | `typography` | `{tanrei.sys.typescale.code-small}` |
| `comp.code-block.code.typescale.medium` | `typography` | `{tanrei.sys.typescale.code}` |
| `comp.code-block.code.color` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.code-block.code.tab-size` | `number` | `2` |
| `comp.code-block.header.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.code-block.header.padding-block-end` | `dimension` | `{tanrei.sys.space.space50}` |
| `comp.code-block.title.typescale` | `typography` | `{tanrei.sys.typescale.label-small}` |
| `comp.code-block.title.color` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.code-block.language.typescale` | `typography` | `{tanrei.sys.typescale.label-small}` |
| `comp.code-block.language.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.code-block.copy-button.inset` | `dimension` | `{tanrei.sys.space.space75}` |
| `comp.code-block.line-number.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.code-block.line-number.gap` | `dimension` | `{tanrei.sys.space.space200}` |
| `comp.code-block.prompt.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.code-block.line.mark.width` | `dimension` | `{tanrei.sys.border.thick}` |
| `comp.code-block.line.highlighted.container.color` | `color` | `{tanrei.sys.color.surface-container-highest}` |
| `comp.code-block.line.highlighted.mark.color` | `color` | `{tanrei.sys.color.primary}` |
| `comp.code-block.line.added.container.color` | `color` | `{tanrei.sys.color.success-container}` |
| `comp.code-block.line.added.mark.color` | `color` | `{tanrei.sys.color.success}` |
| `comp.code-block.line.removed.container.color` | `color` | `{tanrei.sys.color.error-container}` |
| `comp.code-block.line.removed.mark.color` | `color` | `{tanrei.sys.color.error}` |
| `comp.code-block.syntax.color.comment` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.code-block.syntax.color.keyword` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.code-block.syntax.color.string` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.code-block.syntax.color.constant` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.code-block.syntax.color.function` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.code-block.syntax.color.type` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.code-block.syntax.color.tag` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.code-block.syntax.color.property` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.code-block.syntax.color.punctuation` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.code-block.syntax.emphasis.comment` | `number` | `0` |
| `comp.code-block.syntax.emphasis.keyword` | `number` | `{tanrei.sys.typescale.emphasis.body}` |
| `comp.code-block.syntax.emphasis.string` | `number` | `0` |
| `comp.code-block.syntax.emphasis.constant` | `number` | `0` |
| `comp.code-block.syntax.emphasis.function` | `number` | `0` |
| `comp.code-block.syntax.emphasis.type` | `number` | `0` |
| `comp.code-block.syntax.emphasis.tag` | `number` | `0` |
| `comp.code-block.syntax.emphasis.property` | `number` | `0` |
| `comp.code-block.syntax.emphasis.punctuation` | `number` | `0` |
| `comp.code-block.syntax.max-length` | `number` | `50000` |

Per-state tokens, valued by the design system's pattern rules (not written by hand):

- `comp.code-block...` for the variants `filled`, `outlined`, the states  and the properties `container.color`.

### Highlighting

Color comes from one of three sources, in this order.

1. **Runs you give.** Code highlighted where the page was made, or by a highlighter you chose. They are drawn as given, and the block never highlights that code again, whatever `language` and `highlight` say.
2. **The block’s own highlighter**, when `highlight` is true, `language` names a language it knows, and the code is no longer than `comp.code-block.syntax.max-length` (50,000 characters).
3. **Plain**, in every other case.

The code is drawn at once, plain. Its colors arrive a moment later, in one frame, and move nothing. Code that changes is read again, and code that grows at its end keeps the colors it has.

| `language` | What happens |
| --- | --- |
| `html`, `xml`, `svg`, `css`, `javascript` (`js`, `mjs`, `cjs`, `jsx`), `typescript` (`ts`, `tsx`), `json` (`jsonc`), `shell` (`sh`, `bash`, `zsh`), `swift`, `kotlin` (`kt`), `dart` | Highlighted. Case does not matter. |
| empty, `text`, `plain`, `plaintext` | Plain. Nothing is reported. |
| anything else | Plain. A debug build reports the unknown language once. |

The block never guesses a language, not from the code, the `headline` or the `language-label`. Short code is ambiguous, and a wrong guess colors code wrongly.

**Turning it off.** `highlight="false"` turns the block’s own highlighter off for one block. Runs you give are still drawn.

**A limit.** Code longer than `comp.code-block.syntax.max-length` is drawn plain, all of it, never half highlighted. A design system can change the value.

**With added and removed lines**, the block reads the code as the two texts it holds: the code after the change colors the lines that are not removed, and the code before it colors the removed lines. A removed line that opens a string cannot miscolor what follows.

**Failures are quiet.** A highlighter that cannot be loaded, that throws, or whose runs do not join to the code exactly leaves the code plain. The header, the copy button, the lines and the marks keep working.

The grammars are small on purpose. They are meant for showing code, not for editing it. Where a language is hard they can put a run in the wrong color, but they never drop a character.

### Highlighting where the page is made

A site that builds its pages can highlight in the build. The colors are then in the first paint, and the browser loads no highlighter. `highlightToHtml` is the same function the element uses, and it runs in Node.

```js
import { highlightToHtml } from '@tanrei/web/highlight';

const html = await highlightToHtml(source, 'tsx');
// 
${html}

```

`data-syntax-of` on the `` says that the code has been highlighted. The element draws it as given and imports nothing.

### Your own highlighter

`@tanrei/web/highlight` is a module of its own with no dependency. The element imports it the first time a block needs it, and each language’s grammar the first time that language is asked for.

| Export | What it does |
| --- | --- |
| `highlight(code, language)` | The runs, or `null` for a language it does not know. A promise the first time a language is used, a value after. |
| `highlightToHtml(code, language, { lines })` | The inner HTML of the ``. With `lines`, one `` per line. |
| `registerLanguage(names, grammar)` | Adds a language or replaces one. A grammar is data: named states, each a list of rules with a pattern, a role and the state to enter or leave. It may be a function that imports the grammar. |
| `loadLanguage(language)` | Loads a grammar ahead of the first code in it. |
| `setHighlighter(fn)` | Replaces the highlighter whole. `null` turns automatic highlighting off for the page. |
| `languages()` | Every name a language is known by. |
| `foldScope(scopes, text)` | The role for a dotted scope name, by the table below. |
| `tokenize(grammar, code)`, `checkGrammar(grammar)` | For testing a grammar you write. |

A product that already has a highlighter it trusts can also set `TanreiCodeBlock.highlighter` to a function `(code, language, signal) => runs`. The block then asks that function, and Tanrei’s module is never loaded.

### Syntax roles

| Role (`data-syntax`) | What it is | In the default system |
| --- | --- | --- |
| `comment` | A comment, a documentation comment | Quieter than the code |
| `keyword` | One of the language’s own words: a keyword, a modifier, an at-rule, an annotation, an operator written as a word | Purple, one weight step heavier |
| `string` | Text written in the code: a string, a character, a regular expression, the value of a markup attribute | Green |
| `constant` | A value that is not text: a number, a boolean, null, a named constant, a unit, a color value, an escape | Orange |
| `function` | The name of a function or a method, declared or called | Blue |
| `type` | The name of a type: a class, a structure, an interface, a built-in type, a namespace | Blue-green |
| `tag` | What markup and style sheets address: an element’s name, a component’s name in markup, a selector | Red |
| `property` | A name that belongs to something: a property, a key, a markup attribute, a style property, a command’s option | Blue, a tone nearer the code’s color |
| `punctuation` | Brackets, separators, the delimiters of markup | Quieter than the code |
| plain (no span) | Anything else: variables, parameters, operators written as signs, text between tags | The code’s color |

Each role has two tokens: a color (`comp.code-block.syntax.color.*`) and a weight step (`comp.code-block.syntax.emphasis.*`). The roles are a token axis, so a design system can add one. The default system’s green and red come from palettes that are syntax’s own, close in hue to the success and error colors. An added or a removed line is told by its bar, its sign and its label, never by color alone. A role changes color and weight only, so highlighted and plain code have the same lines and columns.

A run is a `` inside the ``. Text outside a span is plain.

### Folding a highlighter’s scopes into the roles

Some highlighters name what they find with dotted scope names from one shared vocabulary. `foldScope` folds them into the roles, so that your highlighter and Tanrei’s give the same colors. A token’s scopes are tried from the most specific outward. Within one scope the first matching row wins. A scope that matches no row is passed over, and a token that matches nothing is plain.

| # | Scope begins with | Role |
| --- | --- | --- |
| 1 | `comment`, `punctuation.definition.comment` | `comment` |
| 2 | `constant.character.escape`, `constant.numeric`, `constant.language`, `constant.other`, `keyword.other.unit`, `support.constant`, `variable.other.constant`, `variable.other.enummember` | `constant` |
| 3 | `string`, `punctuation.definition.string`, `markup.inline.raw`, `markup.raw` | `string` |
| 4 | `entity.name.tag`, `support.class.component`, `meta.selector`, and in style sheets `entity.other.attribute-name` | `tag` |
| 5 | `entity.other.attribute-name`, `support.type.property-name`, `meta.property-name`, `meta.object-literal.key`, `variable.other.property`, `variable.other.object.property`, `support.type.vendored.property-name`, `variable.parameter.option` | `property` |
| 6 | `entity.name.function`, `support.function`, `variable.function`, `meta.function-call.generic` | `function` |
| 7 | `entity.name.type`, `entity.name.class`, `entity.name.namespace`, `entity.other.inherited-class`, `support.type`, `support.class`, `storage.type.primitive`, `storage.type.built-in`, `keyword.type` | `type` |
| 8 | `keyword.operator` whose text is made of letters (`new`, `typeof`, `in`) | `keyword` |
| 9 | `keyword.operator` otherwise | plain |
| 10 | `keyword`, `storage`, `variable.language`, `meta.decorator`, `punctuation.decorator`, `entity.name.function.decorator`, `markup.heading` | `keyword` |
| 11 | `punctuation`, `meta.brace`, `meta.delimiter` | `punctuation` |
| 12 | `variable`, `meta`, `source`, `text`, `markup`, `invalid` | plain |

- A string’s quotes are part of the string. An escape inside a string is a constant.
- JSON keys are properties, and their values strings and constants.
- A decorator’s name is a keyword.
- `invalid` is plain. A code display does not judge code.
- Added and removed are properties of a line (`added-lines`, `removed-lines`), not of a run.

### What the web draws differently

- The element gives each line a box by wrapping it in ``. It moves your nodes and splits text and runs at line breaks, and adds no character to the code. A framework that owns the children of the `` should pass `code` instead, or render `[data-line]` itself.
- A marked line’s label is a hidden `` before the line’s code. It is part of the ``’s `textContent`, and is left out of what is copied.
- The outlined look is drawn on whatever it is placed on. Where that is not the surface color, name it in `--tanrei-code-block-ground`, so the line numbers and the copy button can stand on it while code scrolls under them.
- Before the element is defined, `code.css` draws the fill, the corners, the padding and the runs’ colors. The header, the copy button, the numbers and the marks need the element.
- `highlight` is true by default, so its attribute is written to turn it off: `highlight="false"`. The property takes a boolean.
- The element writes its own runs as spans into your ``, one line at a time, and marks them as its own. A framework that owns the children of the `` should pass `code` and let the element write them.
- The limit is read from the custom property `--tanrei-comp-code-block-syntax-max-length`, as the cascade gives it to the block.
- A page that uses the single-file bundle has the highlighter inside it. A page that imports `@tanrei/web` as modules loads it on demand.

## Guidelines

### Do

- Give a block that can scroll a `headline` or a `label`. The scrolling body is a focus stop and needs a name.
- Use `outlined` inside a card or a panel, and `filled` on a page and on a colored container.
- Use a prompt for a block of commands to type. The prompt is not copied.
- Give every block its `language`. Use `language="text"` for text that has no syntax.
- Put several files or languages in [Tabs](https://tanrei.chnotchy.com/components/tabs/) that each hold a code block.

### Don’t

- Don’t use a code block for a name in a sentence. Use Inline code.
- Don’t rely on syntax colors to say something. The same code drawn plain must say the same thing.
- Don’t mix commands and their output under one prompt. Every line that is not empty gets the prompt. Use two blocks.

## Accessibility

### What the component handles

- The code is the `code` element inside a group named by `headline`, or by `label`.
- A body that can scroll is one stop in the focus order, after the copy button, and scrolls with the arrow keys. A body that fits is not a stop, so a page of short examples adds none.
- Line numbers, signs, bars and the prompt are hidden from assistive technology. A marked line is preceded by its label in words.
- The page never scrolls sideways for a code block, at 320 wide and at twice the text size.
- In forced colors every look gains an edge, all code is the text color, and bars and signs stay.
- Highlighting adds nothing for assistive technology. No role is exposed, and colors that arrive are not announced. The selection, the focus and the scroll position are kept.
- With a red-green color vision deficiency some of the six hues draw together, the green of a string and the red of a tag’s name first. Keywords are also told by weight.

### What you need to do

- Provide `copy-label`, `copied-label` and `copy-failed-label` with `copy`, and the label of each mark you use, in your product’s language.
- Say in the text around the block what a highlighted line shows. The label only says that it is highlighted.