Data Display

CodeBlock

Block container for multi-line source code with optional syntax highlighting and a copy-to-clipboard control.

import { CodeBlock } from '@lostgradient/cinder';
codesnippet
01

Overview

Reference usage

Renders preformatted source code with optional client-side syntax highlighting and copy controls. The first paint may be the escaped plain-code fallback; when highlighting resolves, the block keeps the same layout metrics.

CodeBlock imports no highlighter of its own, so a consumer bundle carries only the grammars it chooses. A block highlights with its highlighter prop, else with the highlighter an ancestor publishes through setCodeHighlighterContext, and renders plain code with neither. Build a highlighter with shikiHighlighter over the grammars your application renders, or use fullShikiHighlighter for every grammar Shiki ships.

Usage

svelte 
<script lang="ts">
  import { CodeBlock } from '@lostgradient/cinder';
  const code = `function greet(name: string): string {
  return \`Hello, \${name}!\`;
}

const message = greet('world');`;
</script>

<CodeBlock {code} />
Live preview

Basic code block

function greet(name: string): string {
  return `Hello, ${name}!`;
}

const message = greet('world');

02

When to use

Use when
  • Displaying a multi-line code sample or terminal transcript inside documentation or chat.
  • Letting the reader copy a snippet to the clipboard via the copyable prop.
Avoid when
  • Annotating a single inline keystroke or shortcut — use kbd instead.
  • Rendering rich prose that happens to include code — embed it in markdown instead.
03

Examples

Basic code block

Multi-line preformatted code.

Delayed highlighting

Colorization can resolve after first paint while the code block keeps its dimensions.

With language label and copy

Header shows the language and a copy-to-clipboard button. The block highlights with the highlighter an ancestor publishes through setCodeHighlighterContext — here, the playground publishes one — and renders plain code when none is published.

04

Props

Props for code-block
Name
Type
Default
Description
code required text The code to render.
language text Optional language label rendered in the header; also selects the grammar for highlighting.
highlight boolean Whether to highlight. Defaults to true whenever language is set and a highlighter resolves from the highlighter prop or from context. highlight={false} is an absolute off switch: it disables ALL highlighting — including an explicit highlighter prop and a context highlighter. The block renders the escaped plain <pre><code> fallback while keeping the language header label. When highlighting is enabled, client-side colorization may appear after first paint, but the block keeps stable layout metrics.
highlighter Highlighter Highlighter for this instance. Receives (code, language) and returns an HTML string (sync or async). Takes precedence over a highlighter an ancestor published through setCodeHighlighterContext; with neither, the block renders unhighlighted.
copyable boolean false When true, render a copy button in the header.
languageLabelVisible boolean true Whether to render the language label in the header. Default true. Pass false to keep language-driven highlighting without the visible header chip; with copyable also unset, no header renders at all.
scrollFadeVisible boolean false Show a scroll-driven fade on the horizontal (inline) edges of the code viewport as a long line overflows — signals "this line continues" rather than dimming a wrapped block. Opt-in and presentation-only. The gradient terminates at partial opacity (not fully opaque) so a half-covered glyph still reads as a glyph, not as a hard cutoff. Defaults to false.