CodeBlock

import { Button } from '@contour-ui/react';

export function SaveButton() {
  return <Button variant="solid">Save</Button>; 
}

import { CodeBlock } from '@contour-ui/react';

<CodeBlock.Root>
  <CodeBlock.Header>
    <CodeBlock.Title>save-button.tsx</CodeBlock.Title>
    <CodeBlock.CopyTrigger />
  </CodeBlock.Header>
  <CodeBlock.Content dangerouslySetInnerHTML={{ __html: highlighted }} />
</CodeBlock.Root>;

CodeBlock frames code that Shiki has already highlighted; it does not highlight by itself. CodeBlock.Content holds Shiki's <pre> and scrolls long lines sideways, and CodeBlock.CopyTrigger copies the code. Every code block on this site is a CodeBlock: the code is highlighted when the site is built, and the MDX pre renders it.

Highlight with Shiki

Use Shiki's css-variables theme. It colors every token with a --shiki-* variable instead of a color, and CodeBlock.Root sets those variables to the syntax colors of the tokens, so the code follows the color theme it is shown in. One theme serves both color themes: no light and dark pair.

import { codeToHtml, createCssVariablesTheme } from 'shiki';

const theme = createCssVariablesTheme();

// On the server or at build time: `highlighted` is the HTML of a <pre>.
const highlighted = await codeToHtml(code, { lang: 'tsx', theme, tabindex: false });

tabindex: false keeps Shiki's pre out of the tab order: CodeBlock.Content is the focusable scroll area.

With Fumadocs, as this site, pass the theme in rehypeCodeOptions. rehypeCode merges a default light and dark pair into these options, and Shiki uses themes whenever it is set, so the one theme goes in as a one-entry themes map whose key is the default color:

fumadocsMdx({
  globalOptions: {
    mdxOptions: {
      rehypeCodeOptions: {
        themes: { tokens: createCssVariablesTheme() },
        defaultColor: 'tokens',
        tabindex: false,
      },
    },
  },
});

Copy

CodeBlock.CopyTrigger is a small ghost icon button that copies the code. Put it in the header, after the title. In a block without a title, put it in CodeBlock.Root itself: it sits at the top end of the block, and the code starts below it, so it never covers a line, however long.

<CodeBlock.Root>
  <CodeBlock.CopyTrigger />
  <CodeBlock.Content dangerouslySetInnerHTML={{ __html: highlighted }} />
</CodeBlock.Root>

It copies its value, or else the value of CodeBlock.Root, or else the text of CodeBlock.Content as it is when clicked: the code as shown, without the notation comments Shiki removed, the line numbers or the signs of a diff. Once the browser has written it, the copy icon turns into a check mark for timeout milliseconds (3 seconds by default), and screen readers hear "Copied to clipboard". The button runs the clipboard of Headless (Clipboard): nothing changes when the browser refuses to write.

On this site every code block gets the button; noCopy in the meta of a code block leaves it out, as in the second block here:

pnpm add @contour-ui/react @contour-ui/tokens

pnpm add @contour-ui/headless-react

Notations

Shiki's notation transformers (@shikijs/transformers, which Fumadocs applies by default) read comments in the code, remove them, and mark the lines with classes. CodeBlock styles those classes:

.contour-button {
  border-radius: var(--ct-radius-control); 
  border-radius: 0; 
}

const root = document.querySelector('#root');
if (root !== null) {
  createRoot(root).render(<App />); 
}

import { themeAttribute } from '@contour-ui/tokens';

document.documentElement.setAttribute(themeAttribute, 'light');

Every line of a diff makes room for the sign, so the code stays aligned. A highlighted word gets no padding either: the columns of monospace code stay where they are.

Line numbers

A pre with data-line-numbers gets its lines numbered, in a column before the code. In Fumadocs, write lineNumbers in the meta of the code block. The numbers come from the CSS counter contour-code-block-line: to start from another number, reset it on the pre, for example counter-reset: contour-code-block-line 9 to start from 10. On this site, lineNumbers=10 does that.

export function ThemeSwitch() {
  const [theme, setTheme] = useState<Theme>(defaultTheme);

  useEffect(() => {
    document.documentElement.setAttribute(themeAttribute, theme);
  }, [theme]);
}

Long lines

Lines never wrap: CodeBlock.Content scrolls them sideways, and every line, a highlighted one too, spans the whole width it scrolls.

pnpm add @contour-ui/react @contour-ui/tokens
pnpm add @contour-ui/react @contour-ui/tokens @contour-ui/icons @contour-ui/headless-react react react-dom

Anatomy

The header is the figure's caption: place it first in CodeBlock.Root, where HTML expects a figcaption, and only with a title. The title takes the free width of the header, and the copy trigger after it sits at the end of the row. While a title is mounted, the root has aria-labelledby with the title's id.

The copy trigger is an IconButton, so it also has the classes and attributes of a button in the ghost variant and the sm size. data-copied is present, and empty, while the code is copied. The status element right after it is empty until a copy, and hidden from sight but not from screen readers.

Props

CodeBlock.Root:

CodeBlock.CopyTrigger:

It also takes the props of button; your onClick runs first, and event.preventDefault() in it cancels the copy. The other parts have no props of their own. Every part takes asChild and the props of its element, such as className, style and id; className is merged with the part's class.

Shiki variables

CodeBlock.Root sets the variables of the css-variables theme to these tokens:

The --shiki-ansi-* colors of ansi code have no tokens and are not set.

Keyboard

Accessibility

• Named by the title only. CodeBlock.Root is a figure named by its title (aria-labelledby), so screen readers announce the block as "save-button.tsx, figure", without the copy button or its status, which share the caption. Until the page's script runs, the caption names it. A block without a title has no caption, and no name: give it one with aria-label on the root.
• A copy button that keeps its name. The trigger is "Copy code" before and after a copy. The check mark is for the eyes; the status element announces "Copied to clipboard" once the browser has written the code, without moving focus.
• One tab stop. CodeBlock.Content is in the tab order, so keyboard users can scroll a long line. Keep the pre out of it (tabindex: false in Shiki), or the block has two tab stops.
• Readable everywhere. Every syntax color keeps at least 4.5:1 on the code background, in both themes. Lines outside a focus take the comment color instead of fading, so they keep that contrast too.
• Code as written. Ligatures are off, so !== shows as three characters, and the code reads left to right on any page. Line numbers are hidden from assistive technology and are not copied; the + and - of a diff are announced.

Tokens