Components / Feedback and display

CodeBlock

Shows code to read and copy, with a header naming the file or language and a copy button.

Source Edit this page

Code with aheader

When to use

Code samples, commands, configuration and output that people read or copy.

Use something else when:

the code is a few characters inside a sentence: <code> in Prose
only a value needs copying: CopyButton next to it

Usage

tsx

import { CodeBlock } from "@arshad-shah/cynosure";

<CodeBlock code={source} title="vite.config.ts" language="ts" />

Highlighting

Cynosure bundles no highlighter. Pass highlight, a function from the code and language to React nodes: Shiki, Prism or your own. Copying always copies the plain code.

tsx

<CodeBlock
  code={source}
  language="ts"
  highlight={(code, lang) => <span dangerouslySetInnerHTML={{ __html: highlighter.codeToHtml(code, { lang }) }} />}
/>

Bring your own highlighter

Line numbers and wrapping

lineNumbers adds a gutter that screen readers skip and selections leave out. wrap wraps long lines instead of scrolling sideways; line numbers are then left out because they could not line up.

Actions

actions puts your own buttons in the header, before the copy button: "Insert into editor", "Run". Use Button or IconButton at size="sm". They keep their size when the block is narrow (the title gives way) and come before the copy button in the tab order. With copyable={false} and no title the header still shows, holding the actions.

tsx

<CodeBlock
  code={sql}
  language="sql"
  actions={<Button size="sm" variant="ghost" icon={plus} onClick={insert}>Insert into editor</Button>}
/>

Actions beside the copy button

Props

Every prop of CodeBlock
Prop	What it does	Type	Default
`code`Required	The code to show and copy. One final new line is not shown as an empty last line.	`string`
`language`	Shown in the header (when there is no `title`) and passed to `highlight`.	`string`
`title`	A file name or caption for the header, e.g. "vite.config.ts".	`ReactNode`
`highlight`	Your highlighter, e.g. `(code, lang) => <span dangerouslySetInnerHTML={{ __html: shiki(code, lang) }} />`. Cynosure bundles none. Without it the code is plain text.	`((code: string, language?: string) => ReactNode)`
`lineNumbers`	Show line numbers beside the code. Left out when `wrap` is on.	`boolean`
`activeLines`	Lines to mark (1-based), such as the line a debugger is on. Marked behind the text and read out.	`readonly number[]`
`wrap`	Wrap long lines instead of scrolling sideways (line numbers are then left out, as they would not line up).	`boolean`
`actions`	Buttons in the header beside the copy button, such as "Insert into editor" or "Run". Use `Button` or `IconButton` at `size="sm"`; they come before the copy button in the reading and tab order.	`ReactNode`
`copyable`	Show the copy button. Default true.	`boolean`	`true`
`copy`	Passed to the copy button (extensions can copy through their own channel).	`((text: string) => Promise<void> \| void)`
`size`	Text size of the code. Default "md".	`Size`	`"md"`
`labels`	Replace the built-in English text: the copy button, the code region's name and the marked lines.	`Partial<CodeBlockLabels>`
`className`	Added to the root element, for layout.	`string`
`style`	Layout only. Restyle through --cy-code-block-* tokens.	`CSSProperties`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Structure: a figure named by its title (or language). Your actions, then the copy button, follow the title in the header; Tab reaches them in that order, then the code region.
Scrolling: code that scrolls sideways is a focusable region named like the block, so keyboard users can Tab to it and scroll with the arrow keys. Tall code scrolls inside the block, line numbers with it.
Copy: the button copies code and announces "Copied"; pass copy to copy through an extension's own channel.
Contrast: code, line numbers and the title keep 4.5:1 in light and dark modes (your highlighter's colours are yours to check).
All built-in text is in labels.

Theming

Tokens: --cy-code-block-background, --cy-code-block-radius and --cy-code-block-max-height.

CopyButton · Prose · Kbd

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

HighlightingLink to "Highlighting"

Line numbers and wrappingLink to "Line numbers and wrapping"

ActionsLink to "Actions"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

ThemingLink to "Theming"

RelatedLink to "Related"