API Reference
Complete documentation for the <code-block> and <code-block-group> custom elements.
<code-block>
The main component for displaying syntax-highlighted code.
Attributes
| 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 |
The first line number shown in the gutter. Subsequent lines increment from this value (e.g. start-line="42" displays as 42, 43, 44…). |
end-line |
number | — | When set, only the slice from start-line through end-line is rendered. Useful for displaying a specific excerpt of a larger source while preserving its original line numbers. |
highlight-lines |
string | — | Lines to highlight. Comma-separated list of line numbers or ranges. Example: "1,3-5,8". Values match the displayed (absolute) numbers — with start-line="42", write highlight-lines="44" to highlight the line that displays as 44. |
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. |
CSS Custom Properties
Container & Layout
| Property | Default | Description |
|---|---|---|
--cb-bg |
theme-aware | Outer container background. |
--cb-code-bg |
theme-aware | Code area background. |
--cb-border-color |
theme-aware | Border color used throughout the component. |
--cb-border-radius |
8px |
Border radius of the outer container. |
--cb-margin |
1rem 0 |
Outer margin of the component. |
--cb-shadow |
theme-aware | Box shadow on dropdown menus. |
Typography
| Property | Default | Description |
|---|---|---|
--cb-font-family |
Consolas, Monaco, Courier New, monospace |
Font for code text and filename. |
--cb-ui-font-family |
-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif |
Font for UI elements (buttons, menus, expand bar). |
--cb-font-size |
0.875rem |
Base font size for code. |
--cb-text-color |
theme-aware | Default text color for code. |
--cb-line-height |
1.6 |
Line height for code lines and line numbers. |
Header
| Property | Default | Description |
|---|---|---|
--cb-header-bg |
theme-aware | Background color of the header bar. |
--cb-header-padding |
0.5rem 1rem |
Padding inside the header bar. |
--cb-label-color |
theme-aware | Color for language labels and action button icons. |
--cb-filename-color |
theme-aware | Color for the filename text. |
Copy & Action Buttons
| Property | Default | Description |
|---|---|---|
--cb-button-bg |
theme-aware | Button background color. |
--cb-button-color |
theme-aware | Button text color. |
--cb-button-border |
theme-aware | Button border color. |
--cb-button-border-width |
1px |
Button border width. |
--cb-button-border-style |
solid |
Button border style (e.g., solid, none, dashed). |
--cb-button-radius |
4px |
Border radius for copy and action buttons. |
--cb-button-padding |
4px 12px |
Padding inside the copy button. |
--cb-button-font-size |
0.75rem |
Font size for the copy button. |
--cb-button-hover-bg |
theme-aware | Copy button background on hover. |
--cb-button-hover-border |
theme-aware | Copy button border color on hover. |
--cb-action-button-hover-bg |
theme-aware | Icon button (share/download) background on hover. |
--cb-success-color |
#238636 |
Color for the "Copied!" success state. |
--cb-error-color |
#da3633 |
Color for the copy-failed state. |
--cb-focus-color |
theme-aware | Focus ring color for interactive elements. |
Code Area
| Property | Default | Description |
|---|---|---|
--cb-code-padding |
1rem |
Padding inside the code area and line-numbers gutter. |
--cb-max-height |
none | Maximum height before scrolling (set via max-height attribute). |
Line Numbers
| Property | Default | Description |
|---|---|---|
--cb-line-numbers-bg |
theme-aware | Background of the line-numbers gutter. |
--cb-line-numbers-color |
theme-aware | Text color for line numbers. |
--cb-line-numbers-highlight-color |
theme-aware | Text color for highlighted line numbers. |
Line Highlighting & Focus Mode
| Property | Default | Description |
|---|---|---|
--cb-highlight-bg |
theme-aware | Background color for highlighted lines. |
--cb-highlight-border |
theme-aware | Left border accent on highlighted lines. |
--cb-highlight-gutter |
theme-aware | Background of highlighted line-number cells. |
--cb-focus-dim-opacity |
0.4 |
Opacity for non-highlighted lines in focus mode. |
--cb-focus-blur |
0.5px |
Blur applied to non-highlighted lines in focus mode. |
Diff
| Property | Default | Description |
|---|---|---|
--cb-diff-add-bg |
theme-aware | Background for added lines. |
--cb-diff-add-border |
theme-aware | Left border for added lines. |
--cb-diff-add-color |
theme-aware | Line-number color for added lines. |
--cb-diff-add-gutter |
theme-aware | Gutter background for added lines. |
--cb-diff-add-text |
theme-aware | Text color for added-line markers. |
--cb-diff-remove-bg |
theme-aware | Background for removed lines. |
--cb-diff-remove-border |
theme-aware | Left border for removed lines. |
--cb-diff-remove-color |
theme-aware | Line-number color for removed lines. |
--cb-diff-remove-gutter |
theme-aware | Gutter background for removed lines. |
--cb-diff-remove-text |
theme-aware | Text color for removed-line markers. |
Expand / Collapse
| Property | Default | Description |
|---|---|---|
--cb-expand-bg |
theme-aware | Background of the expand/collapse bar. |
--cb-expand-color |
theme-aware | Text color of the expand/collapse bar. |
--cb-expand-hover-bg |
theme-aware | Hover background of the expand/collapse bar. |
Scrollbar
| Property | Default | Description |
|---|---|---|
--cb-scrollbar-track |
theme-aware | Scrollbar track background. |
--cb-scrollbar-thumb |
theme-aware | Scrollbar thumb color. |
--cb-scrollbar-thumb-hover |
theme-aware | Scrollbar thumb hover color. |
Menus
| Property | Default | Description |
|---|---|---|
--cb-menu-radius |
8px |
Border radius for dropdown menus. |
Syntax Highlighting Colors
| Property | Default (Light) | Default (Dark) | Description |
|---|---|---|---|
--cb-keyword |
#d73a49 |
#ff7b72 |
Keywords (if, return, class, etc.). |
--cb-string |
#22863a |
#a5d6ff |
String literals. |
--cb-comment |
theme-aware | theme-aware | Comments. |
--cb-function |
#6f42c1 |
#d2a8ff |
Function names. |
--cb-number |
#005cc5 |
#79c0ff |
Numeric literals. |
--cb-attribute |
#005cc5 |
#79c0ff |
HTML/XML attributes. |
--cb-tag |
#22863a |
#7ee787 |
HTML/XML tag names. |
--cb-meta |
#e36209 |
#ffa657 |
Meta/preprocessor tokens. |
--cb-builtin |
#d73a49 |
#ffa198 |
Built-in names. |
Server-Side Rendering (SSR)
Pre-render code blocks at build time for static sites. Import from @profpowell/code-block/ssr.
Functions
| Function | Returns | Description |
|---|---|---|
prerenderCodeBlock(options) |
string |
Pre-render a single code block. Returns complete <code-block data-ssr> HTML with Declarative Shadow DOM. |
prerenderCodeBlocksInHtml(html) |
string |
Process an HTML string, pre-rendering all <code-block> elements. Skips blocks with src or data-ssr attributes. |
SSR Attributes
| Attribute | Description |
|---|---|
data-ssr |
Added automatically by the SSR module. Tells the client-side component to skip re-rendering and hydrate interactivity only. |
Events
| 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. |
Methods
| 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. |
Slots
| Slot | Description |
|---|---|
| (default) | The code content to display. Can be plain text or pre-formatted. |
<code-block-group>
Container component for displaying multiple code blocks in a tabbed interface.
Attributes
| 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). |
Events
| Event | Detail | Description |
|---|---|---|
tab-changed |
{ index: number, filename: string } |
Fired when the active tab changes. |
Methods
| 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. |
Usage Notes
- Child
<code-block>elements should have afilenameattribute for tab labels. - Theme is automatically propagated to all child code blocks.
- Tabs are generated from child elements in DOM order.
Supported Languages
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) |
Installation
npm
Import in JavaScript
CDN
Browser Support
The component works in all modern browsers that support:
- Custom Elements v1
- Shadow DOM v1
- ES Modules
- CSS Custom Properties
This includes Chrome 67+, Firefox 63+, Safari 12.1+, and Edge 79+.