CodeBlock

Hero example

curl https://api.mattermode.com/v1/entities

When to use

Reach for <CodeBlock> whenever rendering literal code or structured request / response payloads. The 5-token syntax palette (<Tok kind>) handles key / string / number / punct / comment without pulling in a syntax highlighter. The translucent-white surface is canonical — never dark slate. For long-form prose code, bare-<pre> mode is correct. For endpoint demos and API recipes, pass a header to render the card-style surface that V1 <CodeCard> carried.

Don't reach for CodeBlock for inline code spans — use Markdown backticks, which fall through to the styled <code> recipe. Don't use it for terminal output where you want a dark-slate aesthetic — Matter's code surface is intentionally light, even in dark theme.

Anatomy

Bare mode renders a single <pre class="code">. Card mode (header set) wraps in <figure class="code-card"> with a 44px .code-card-head row and the .code body underneath — geometry mirrors V1 .matter-code-card exactly so the consumer-migration step (action 9) lands as a pixel-parity swap.

The <Tok> companion component colorizes spans inside the code body:

Header slot — V1 CodeCard replacement

// V1 (today)
<CodeCard verb="POST" path="/v1/entities" time="142ms">
  …
</CodeCard>

// V2 (action 9 migration)
<CodeBlock
  header={
    <>
      <EndpointBadge method="POST" path="/v1/entities" />
      <span className="code-time">142ms</span>
    </>
  }
>
  …
</CodeBlock>

The header slot accepts any ReactNode, so consumers can compose it however they need — verb chip, branch indicator, file path, response status, etc. The outer element switches to <figure> when a header is present so consumers may include a <figcaption> for accessible description.

Props

States

CodeBlock is single-state. Header mode and bare mode are configuration, not state.

Density

curl https://api.mattermode.com/v1/entities

curl https://api.mattermode.com/v1/entities

In compact, the code body padding drops from 16 to 12px. Font size and line-height stay constant — code legibility is the floor.

Themes

curl https://api.mattermode.com/v1/entities

curl https://api.mattermode.com/v1/entities

curl https://api.mattermode.com/v1/entities

In dark, the translucent-white surface inverts to a translucent ink (still light against the dark backdrop) and the Tok colors shift to their dark-theme variants. In forced-colors, Tok colors collapse to system foreground; the surface collapses to Canvas with ButtonBorder.

Tokens consumed

Surface reads --code-surface. Header band reads --code-head. Tok colors resolve through --tok-k / --tok-s / --tok-n / --tok-p / --tok-c.

Accessibility

• Keyboard interactions. None — the <pre> is a static surface. Triple-click selects the block.
• ARIA roles and properties. <pre> carries no role override. <figure> (when header is set) inherits semantic figure role; consumer may add a <figcaption>.
• Focus order. N/A.
• Screen-reader expectations. Code is announced verbatim. Tok spans inherit accessibility — colour is purely visual.
• Reduced motion. N/A.
• Forced colors. Tok colors → system foreground; surface → Canvas with ButtonBorder.
• WIG rules. <pre> for monospace code (semantic-element rule). <figure> + optional <figcaption> for captioned code (semantic-element rule). Comment Tok meets AA — verify when surface is tinted.

Do / Don't

Recipes

This component appears in:

• API recipe — every endpoint demo.
• Docs corpus recipe — inline code in agent replies.

Code example

import { CodeBlock, Tok, EndpointBadge } from "@matter/components";

export function CreateEntityExample() {
  return (
    <CodeBlock
      header={
        <>
          <EndpointBadge method="POST" path="/v1/entities" />
          <span className="code-time">142ms</span>
        </>
      }
    >
      <Tok kind="c">{`// Create a Delaware C-Corp`}</Tok>{"\n"}
      <Tok kind="k">curl</Tok> <Tok kind="s">"https://api.mattermode.com/v1/entities"</Tok>{"\n"}
      {"  -H "}<Tok kind="s">"Authorization: Bearer sk_test_…"</Tok>
    </CodeBlock>
  );
}

Source