API Reference

Complete documentation for the <code-block> and <code-block-group> custom elements.

<code-block>

The main component for displaying syntax-highlighted code.

Attribute	Type	Default	Description
`language`	string	`"plaintext"`	Programming language for syntax highlighting. Supports: javascript, typescript, python, css, html, json, yaml, bash, shell, php, ruby, go, rust, sql, xml, markdown, diff, plaintext.
`filename`	string	—	Displays a filename in the header. Also used as the default download filename.
`show-lines`	boolean	`false`	Shows line numbers in the gutter.
`start-line`	number	`1`	Starting line number when `show-lines` is enabled.
`highlight-lines`	string	—	Lines to highlight. Comma-separated list of line numbers or ranges. Example: `"1,3-5,8"`
`theme`	string	`"light"`	Color theme. Values: `"light"`, `"dark"`, or `"auto"` (follows system preference).
`collapsed`	boolean	`false`	Renders the code block in a collapsed state. Click to expand.
`show-download`	boolean	`false`	Adds a download button to save the code as a file.
`no-copy`	boolean	`false`	Hides the copy button and prevents text selection (user-select: none).
`lazy`	boolean	`false`	Defers syntax highlighting until the element is visible in the viewport.
`focus-mode`	boolean	`false`	Dims non-highlighted lines to draw attention to specific code. Use with `highlight-lines`.
`src`	string	—	URL to load code content from. Language and filename are auto-detected from the URL if not specified. Dispatches `code-loaded` or `code-load-error` events.

Property	Default (Light)	Default (Dark)	Description
`--cb-border-radius`	`8px`	`8px`	Border radius of the code block container.
`--cb-header-bg`	`#f6f8fa`	`#161b22`	Background color of the header bar.
`--cb-code-bg`	`#ffffff`	`#0d1117`	Background color of the code area.
`--cb-border-color`	`#d0d7de`	`#30363d`	Border color around the code block.
`--cb-text-color`	`#24292f`	`#c9d1d9`	Default text color for code.
`--cb-label-color`	`#57606a`	`#8b949e`	Color for filename and language labels.
`--cb-line-number-color`	`#6e7781`	`#6e7681`	Color for line numbers.
`--cb-highlight-bg`	`#fff8c5`	`#2d333b`	Background color for highlighted lines.
`--cb-keyword`	`#cf222e`	`#ff7b72`	Color for language keywords.
`--cb-string`	`#0a3069`	`#a5d6ff`	Color for string literals.
`--cb-comment`	`#6e7781`	`#8b949e`	Color for comments.
`--cb-function`	`#8250df`	`#d2a8ff`	Color for function names.
`--cb-number`	`#0550ae`	`#79c0ff`	Color for numeric literals.
`--cb-operator`	`#cf222e`	`#ff7b72`	Color for operators.
`--cb-class`	`#953800`	`#ffa657`	Color for class names.

Event	Detail	Description
`code-copied`	`{ code: string }`	Fired when code is copied to clipboard.
`code-expanded`	—	Fired when a collapsed code block is expanded.
`code-collapsed`	—	Fired when a code block is collapsed.
`code-loaded`	`{ url: string, code: string }`	Fired when external code (via `src`) is successfully loaded.
`code-load-error`	`{ url: string, error: string }`	Fired when external code (via `src`) fails to load.

Method	Parameters	Returns	Description
`copyCode()`	—	`Promise<void>`	Copies the code content to clipboard.
`getCode()`	—	`string`	Returns the raw code content.
`highlight()`	—	`void`	Manually triggers syntax highlighting.
`expand()`	—	`void`	Expands a collapsed code block.
`collapse()`	—	`void`	Collapses the code block.

Slot	Description
(default)	The code content to display. Can be plain text or pre-formatted.

Container component for displaying multiple code blocks in a tabbed interface.

Attribute	Type	Default	Description
`theme`	string	`"light"`	Color theme applied to all child code blocks.
`active`	number	`0`	Index of the initially active tab (0-based).

Event	Detail	Description
`tab-changed`	`{ index: number, filename: string }`	Fired when the active tab changes.

Method	Parameters	Returns	Description
`setActiveTab(index)`	`index: number`	`void`	Programmatically switches to the specified tab.
`getActiveTab()`	—	`number`	Returns the index of the currently active tab.

Child <code-block> elements should have a filename attribute for tab labels.
Theme is automatically propagated to all child code blocks.
Tabs are generated from child elements in DOM order.

The following languages are bundled and available for syntax highlighting:

Language	Aliases	Description
`javascript`	js	JavaScript (ES6+)
`typescript`	ts	TypeScript
`python`	py	Python
`css`	—	CSS (including modern features)
`html`	—	HTML
`json`	—	JSON
`yaml`	yml	YAML
`bash`	sh, shell	Bash/Shell scripts
`php`	—	PHP
`ruby`	rb	Ruby
`go`	golang	Go
`rust`	rs	Rust
`sql`	—	SQL
`xml`	—	XML
`markdown`	md	Markdown
`diff`	patch	Unified diff format
`plaintext`	text, txt	Plain text (no highlighting)

npm install @profpowell/code-block

import '@profpowell/code-block';

The component works in all modern browsers that support:

This includes Chrome 67+, Firefox 63+, Safari 12.1+, and Edge 79+.