PlCodeBlock

A viewer for one line of code or a thousand, with a bar over it, numbers down the side, a prompt in front of every line, and twelve palettes to read it in.

React

import { PlCodeBlock } from 'plass-ui';

<PlCodeBlock code={source} language="tsx" title="src/Save.tsx" />;

import 'package:plass_ui/plass_ui.dart';

PlCodeBlock(
  code: source,
  language: 'dart',
  title: const Text('lib/save.dart'),
);

Everything it draws above the code is optional and off one prop each, because the same component has to be a snippet inside a sentence (no bar, no numbers, no chrome), and the full transcript at the top of a README.

Props

Prop	Type	Default	Description
code *	string	—	The code. Trailing whitespace is trimmed off the end of the block
language	string	—	What it is written in — ts, dart, bash, yml. The common spellings and file extensions are understood
theme	'dark' | 'light' | 'auto' | 'mono' | (string & {})	'dark'	The palette. Independent of the page's light and dark, except on auto. Any other string works too
highlight	boolean	true	Colours the code. Off, the grammar engine is not fetched at all
toolbar	boolean	true	The bar over the code, and the master switch for showLanguage, copyable and rawToggle
title	ReactNode	—	A name at the start of the bar — a file path, usually
showLanguage	boolean	true	Names the language at the start of the bar
copyable	boolean	true	The button that puts the code on the clipboard
rawToggle	boolean	false	The toggle that drops the colouring and shows the characters as they are
highlightLines	number | string | Array<number | string>	—	Lines to mark: 4, '4-9', '1,4-9,12'. Counted the way the gutter counts
lineNumbers	boolean	false	Numbers down the side
startLine	number	1	What the first line is numbered
prompt	string	—	A shell prompt in front of every line that has something on it. Drawn but never copied
wrap	boolean	false	Wraps long lines instead of scrolling them sideways
maxHeight	number | string	—	How tall the block may get before the code scrolls inside it. A number is pixels
fontFamily	string	—	The typeface. Defaults to the page's own monospace stack
fontSize	number | string	—	Overrides the size the size ladder chose
lineHeight	number | string	—	Overrides the leading. A bare number is a ratio, as in CSS
letterSpacing	number | string	—	Tracking
copyLabel	string	'Copy'	The copy button's label
copiedLabel	string	'Copied'	And what it says once the code is on the clipboard
copyFailedLabel	string	'Could not copy'	And what it says when the clipboard refused
rawLabel	string	'Raw'	The raw toggle's label
codeLabel	string	'Code'	What the region is called when there is neither a title nor a language
onCopy	(code: string) => void	—	Fires with the copied text once the clipboard has taken it
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The type scale and the air around the code
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. It reaches the focus ring and nothing else — the block itself refuses the family on purpose
densityshared	'default' | 'compact'	'default'	The air around the code. Never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 is flat

Prop	Type	Default	Description
code *	String	—	The code. Trailing whitespace is trimmed off the end of the block
lines	List<PlCodeLine>?	—	The same code already coloured, one entry per line — what a caller's own highlighter produced
language	String?	—	What it is written in. Drawn on the bar; nothing else reads it
theme	String	'dark'	The palette. Independent of the page's light and dark, except on auto. Any other string works too
customTheme	PlCodeTheme?	—	A palette of the caller’s own, which wins over theme when it is given
toolbar	bool	true	The bar over the code, and the master switch for showLanguage, copyable and rawToggle
title	Widget?	—	A name at the start of the bar — a file path, usually
showLanguage	bool	true	Names the language at the start of the bar
copyable	bool	true	The button that puts the code on the clipboard
rawToggle	bool	false	The toggle that drops the colouring and shows the characters as they are
highlightLines	String?	—	Lines to mark: '4', '4-9', '1,4-9,12'. One string rather than React's number-or-string-or-list
lineNumbers	bool	false	Numbers down the side
startLine	int	1	What the first line is numbered
prompt	String?	—	A shell prompt in front of every line that has something on it. Drawn but never copied
wrap	bool	false	Wraps long lines instead of scrolling them sideways
maxHeight	double?	—	How tall the block may get before the code scrolls inside it. A number is pixels
fontFamily	String?	—	The typeface. Defaults to the page's own monospace stack
fontSize	double?	—	Overrides the size the size ladder chose
lineHeight	double?	—	Overrides the leading, as a multiple of the font size
letterSpacing	double?	—	Tracking
copyLabel	String?	'Copy'	The copy button's label
copiedLabel	String?	'Copied'	And what it says once the code is on the clipboard
copyFailedLabel	String?	'Could not copy'	And what it says when the clipboard refused
rawLabel	String?	'Raw'	The raw toggle's label
codeLabel	String?	'Code'	What the region is called when there is neither a title nor a language
onCopy	ValueChanged<String>?	—	Fires with the copied text once the clipboard has taken it
sizeshared	PlassSize	PlassSize.md	The type scale and the air around the code
colorshared	PlassColor	PlassColor.primary	Semantic colour role. It reaches the focus ring and nothing else — the block itself refuses the family on purpose
densityshared	PlassDensity	PlassDensity.standard	The air around the code. Never the type scale
elevationshared	int	0	Drop shadow depth. 0 is flat

Every native <div> attribute passes straight through. color is excluded because it collides with the color in the table above, title and prefix because the component spells them itself, children because the code is code, and onCopy because the component's fires with the text rather than with an event.

PlCodeToken

PlCodeToken is not in the React package yet.

Prop	Type	Default	Description
text *	String	—	The characters
kind	PlCodeTokenKind?	—	Which slot colours them, or null for the foreground

PlCodeTokenKind is the twelve slots a theme declares: comment, keyword, string, number, function, type, variable, tag, attribute, meta, addition and deletion. A PlCodeTheme is those twelve plus a background and a foreground. The other five colours a block draws with are derived from those two, so a palette of your own is fourteen values rather than nineteen.

What the shared axes mean across the library is in prop conventions.

Examples

theme

The palette is independent of the page's light and dark, except on auto. dark is the default and it is the one that is not a preference: code has been read on a dark ground since terminals, and a block that matched the page would be the one element on it whose colours were chosen by something other than the code.

React

import { useState } from 'react';
import { PlCodeBlock, PlSelect, type PlCodeBlockTheme } from 'plass-ui';

const source = `const routes = new Map<string, Handler>();

/** Answers /health, and nothing else. */
export function health(request: Request): Response {
  return new Response('ok', { status: 200 });
}`;

const themes: PlCodeBlockTheme[] = [
  'dark',
  'light',
  'auto',
  'mono',
  'one-dark',
  'dracula',
  'monokai',
  'nord',
  'night-owl',
  'gruvbox',
  'github',
  'solarized-light'
];

export default function CodeBlockThemes() {
  const [theme, setTheme] = useState<PlCodeBlockTheme>('dracula');

  return (
    <div className="flex w-full flex-col gap-3">
      <PlSelect
        label="Theme"
        value={theme}
        onValueChange={(next) => setTheme(next as PlCodeBlockTheme)}
        items={themes.map((name) => ({ value: name, label: name }))}
      />
      <PlCodeBlock code={source} language="ts" theme={theme} />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

const String _source = '''final routes = <String, Handler>{};

/// Answers /health, and nothing else.
Response health(Request request) {
  return Response('ok', status: 200);
}''';

const List<String> _themes = <String>[
  'dark',
  'light',
  'auto',
  'mono',
  'one-dark',
  'dracula',
  'monokai',
  'nord',
  'night-owl',
  'gruvbox',
  'github',
  'solarized-light',
];

class CodeBlockThemes extends StatefulWidget {
  const CodeBlockThemes({super.key});

  @override
  State<CodeBlockThemes> createState() => _CodeBlockThemesState();
}

class _CodeBlockThemesState extends State<CodeBlockThemes> {
  String _theme = 'dracula';

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      mainAxisSize: MainAxisSize.min,
      children: <Widget>[
        PlSelect<String>(
          label: const Text('Theme'),
          value: _theme,
          onChanged: (String? next) => setState(() => _theme = next ?? 'dark'),
          options: <PlSelectOption<String>>[
            for (final String name in _themes)
              PlSelectOption<String>(value: name, label: Text(name)),
          ],
        ),
        const SizedBox(height: 12),
        PlCodeBlock(code: _source, language: 'dart', theme: _theme),
      ],
    );
  }
}

Four are the house's, dark, light, auto and mono, which has no hue in it at all and carries the structure by weight instead. The other eight are ports kept at the hex they were published in: one-dark, dracula, monokai, nord, night-owl, gruvbox, github and solarized-light. A code block is the one component whose colours a reader already has an opinion about.

theme takes any string, which is how a project brings its own:

[data-code-theme='ours'] {
  --p-code-bg: #101820;
  --p-code-fg: #e8e8e8;
  --p-code-keyword: #ff6b6b;
  /* …eleven more */
}

Sixteen slots, five of which are derived from the other two and need no declaration. Nothing to register and nothing to import.

There is no stylesheet here, so a palette of your own is a PlCodeTheme handed to customTheme rather than a block of CSS:

PlCodeBlock(
  code: source,
  customTheme: const PlCodeTheme(
    background: Color(0xFF101820),
    foreground: Color(0xFFE8E8E8),
    keyword: Color(0xFFFF6B6B),
    // …eleven more
  ),
);

lineNumbers

Numbers down the side, starting wherever startLine says. highlightLines marks rows, a tint with a rule down the leading edge, and it counts the way the gutter counts, so a block that starts at 551 is marked with '553-555'.

React

import { PlCodeBlock } from 'plass-ui';

const source = `export function surfaceSlots(color, elevation) {
  return {
    '--p-accent': \`var(--plass-\${color}-accent)\`,
    '--p-soft': \`var(--plass-\${color}-soft)\`,
    '--p-elev': \`var(--plass-shadow-\${elevation})\`
  };
}`;

export default function CodeBlockLines() {
  return (
    <PlCodeBlock
      code={source}
      language="js"
      title="internal/styles.ts"
      lineNumbers
      startLine={551}
      highlightLines="553-555"
      className="w-full"
    />
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

const String _source = '''PlassSurface surfaceSlots(PlassColor color, int elevation) {
  return PlassSurface(
    ink: family.accent,
    fill: family.soft,
    shadows: tokens.elevation(elevation),
  );
}''';

class CodeBlockLines extends StatelessWidget {
  const CodeBlockLines({super.key});

  @override
  Widget build(BuildContext context) {
    return const PlCodeBlock(
      code: _source,
      language: 'dart',
      title: Text('internal/styles.dart'),
      lineNumbers: true,
      startLine: 551,
      highlightLines: '553-555',
    );
  }
}

The mark's tint is mixed from the theme's own ink rather than from the page's colour family, so it is legible on all twelve palettes and is never the one colour on a Dracula block that nobody chose.

prompt

A shell prompt in front of every line that has something on it. It is drawn but never copied: a $ a reader pastes into their shell is a $ their shell chokes on, so a transcript stays a transcript and still pastes.

React

import { PlCodeBlock } from 'plass-ui';

const source = `npm install plass-ui

npm run dev`;

export default function CodeBlockTerminal() {
  return (
    <PlCodeBlock code={source} language="bash" prompt="$" showLanguage={false} className="w-full" />
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

const String _source = '''flutter pub add plass_ui

flutter run''';

class CodeBlockTerminal extends StatelessWidget {
  const CodeBlockTerminal({super.key});

  @override
  Widget build(BuildContext context) {
    return const PlCodeBlock(code: _source, language: 'bash', prompt: r'$', showLanguage: false);
  }
}

Line numbers are the same: neither is a text node, and neither reaches the clipboard.

Colouring

highlight.js, reached through a dynamic import. The grammars are forty kilobytes and there are thirty-five of them, so they arrive as their own chunk, one language at a time, and only for a block that asked to be coloured. With highlight={false} nothing is fetched at all.

The block draws plain on the first frame and colours itself when the grammar lands. language understands the common spellings and file extensions, so a value copied off a fenced code block works as-is: ts, tsx, js, sh, yml, dart, py, rb, rs, md.

A language nothing here knows is drawn plain rather than refused. Teach it one with registerLanguage:

import { registerLanguage } from 'plass-ui';
import elixir from 'highlight.js/lib/languages/elixir';

registerLanguage('elixir', elixir);

Call it at module scope. A language registered after a block has drawn does not repaint that block, but every block mounted after it sees it.

rawToggle puts a second button on the bar that drops the colouring and shows the characters as they are.

This build does not colour the code and the React one does. That side reaches highlight.js through a dynamic import; this package has no dependencies, and a hand-written grammar for thirty-five languages is a promise it could not keep.

So a caller who has a highlighter hands the result in as lines, and a caller who does not gets the frame, the twelve palettes and the code drawn in one ink:

PlCodeBlock(
  code: source,
  language: 'dart',
  lines: const <PlCodeLine>[
    <PlCodeToken>[
      PlCodeToken('const', PlCodeTokenKind.keyword),
      PlCodeToken(' answer = '),
      PlCodeToken('42', PlCodeTokenKind.number),
      PlCodeToken(';'),
    ],
  ],
);

rawToggle then puts a second button on the bar that drops those runs back to one ink. With no lines there is nothing to drop and no button is drawn.

wrap and maxHeight

wrap folds long lines instead of scrolling them sideways; maxHeight bounds the block and scrolls the code inside it. They are separate answers to the same problem and both can be on.

<PlCodeBlock code={source} language="ts" wrap maxHeight={280} />

Scrolled sideways, the gutter and the prompts stay put: the rows are as wide as the longest line rather than as wide as the window onto them, so every line's number starts at the same place.

Accessibility

• The code is a focusable region with a name, the title, then the language, then the word for code. A scrollable region has to be reachable by a keyboard that has no pointer to drag with, and a focusable region has to have a name.
• Mod + A inside the block selects the block, not the page around it. The browser's own answer is never what a reader who tabbed to a code listing was after.
• The numbers and the prompts are outside the selection for the same reason they are outside the clipboard: there is nothing there to select.

• The copy button changes its own label, which a screen reader reading the page rather than the button would never hear, so the block also announces it through an aria-live region, one word long.
• The raw toggle carries aria-pressed.

• Each bar button is a Semantics node with button: true and a name of its own, and it excludes what is inside it: the copy button draws its own word as well as carrying it, and a reader told "Copy, Copy" has been told once too often.