Code Block

Anatomy

A composable code, output and diff display with optional header, actions and footer. The original Props and render API remains available. A small built-in server-side tokenizer and explicitly trusted external highlighting markup are optional.

maud_ui::primitives::code_block

Props

Generated from public Rust fields. Defaults are evaluated from the implementation.

Prop	Type	Default	Description
`code`	`String`	`""`	Raw source — used when `pre_rendered` is `None`. Highlighted per `Props::language` when the language is recognised.
`pre_rendered`	`Option<String>`	`None`	Optional pre-rendered HTML (e.g. from a syntax-highlighter). Takes precedence over `code` and the built-in highlighter when set.
`language`	`Option<String>`	`None`	Language label shown in the header (e.g. "rust", "bash"). When set to a recognised token, drives the built-in highlighter; unknown values fall back to plain-text rendering.
`filename`	`Option<String>`	`None`	Optional filename shown next to the language.
`show_copy`	`bool`	`true`	Whether to render the copy button (default true).
`max_height`	`Option<String>`	`None`	Optional max-height (CSS) — enables vertical scrolling when set.

Examples

fn main() {
    println!("hello, maud-ui!");
}

curl -X POST https://api.example.com/v1/sessions \
  -H 'x-api-key: sk_live_…' \
  -d '{"prompt":"hi"}'

Usage and composition

Import

use maud_ui::primitives::code_block::{self, Props};

Example

use maud::html;
use maud_ui::primitives::code_block;

html! {
    (code_block::render(code_block::Props {
        code: "fn main() {\n    println!(\"hello, maud-ui!\");\n}".into(),
        language: Some("rust".into()),
        filename: Some("src/main.rs".into()),
        show_copy: true,
        ..Default::default()
    }))
}

Note on show_copy's default: this field is true by default, and Props has a hand-written impl Default rather than a derived one specifically to make that so. Until 0.4.0 the Default was derived, which gave bool::default() — false — while the field's own doc comment claimed "default true"; every ..Default::default() construction silently dropped the copy button. Corrected in 0.4.0, when this primitive was first registered.

Header visibility: the header row (language/filename/copy button) only renders when at least one of language, filename is Some(_), or show_copy is true (has_header = props.language.is_some() || props.filename.is_some() || show_copy). Otherwise render emits a bare <pre><code> with no header.

Language selection & built-in highlighting: language is matched case-insensitively (to_ascii_lowercase()) against:

Any other value (or language: None) skips the tokenizer entirely and renders code as plain, unhighlighted text. pre_rendered, when Some, bypasses the built-in highlighter regardless of language.

Composable API

root(RootOptions, children) accepts Size::{Default, Small} and Variant::{Default, Destructive}. Compose header, title, actions, content, line, and footer with Maud markup. A direct child actions floats; inside a header it remains in the header. copy_button(value) copies that explicit string and announces successful copying. The original render(Props) continues to copy the displayed preformatted content.

ContentOptions controls wrapping, line numbers, first line number and optional maximum height. text_content escapes a string and generates numbered lines when requested. For decorated lines, pass line(LineVariant::{Default, Added, Removed, Highlighted}, markup) elements to content. Empty lines retain a newline for native selection. Line-number and diff decorations are not part of selected text. Content is LTR and keyboard-focusable regardless of page direction.

highlight_code exposes the existing small server-side tokenizer. It is not Shiki; unsupported languages retain their existing marker. Callers may explicitly provide trusted highlighted Markup, but arbitrary trusted HTML is not automatically split into lines. Arbitrary caller actions, including downloads, can be placed in actions; there is no built-in download helper.

use maud::html;
use maud_ui::primitives::code_block::{self, ContentOptions, RootOptions};
let value = "first line\n\nthird line\n";
let block = code_block::root(RootOptions::default(), html! {
    (code_block::header(html! {
        (code_block::title(html! { "Output" }))
        (code_block::actions(code_block::copy_button(value)))
    }))
    (code_block::text_content(ContentOptions { line_numbers: true, ..Default::default() }, value))
});

Message, Diff, ToolCall, StreamingCursor — CodeBlock is part of the AI-chat/agent primitive family and commonly appears embedded inside Message bodies, Diff views, and ToolCall output panels.

Shadcn reference

The composable API corresponds to the official shadcn/ui Code Block. The original language/filename convenience renderer and built-in tokenizer are Maud extensions.

Theme roles (0.9.1)

The --mui-code-* properties now alias the shared text and semantic ink tokens instead of maintaining separate editor palettes. Comments use muted ink; keywords use violet, strings success, numbers warning, types and flags info, lifetimes accent, variables rose, and null muted. All eleven color roles pass 4.5:1 on the code surface across the eight gallery presets. Consumer overrides of --mui-code-* remain available.

Accessibility

The content is a native focusable <pre><code> region. Copy controls are native type="button" buttons; their label and polite status change to “Copied” only after clipboard success, then reset after two seconds. Pseudo-element line numbers and diff markers are excluded from selection. The caller remains responsible for accessible labels on custom actions.

← Back to Gallery