code-block

A feature-rich code block web component with syntax highlighting, copy-to-clipboard, and extensive customization options. Designed for tutorials, documentation, and educational content.

Highlights

See the live demo for all features in action

| Feature | Description | |---------|-------------| | Multi-File Tabs | Tabbed interface for related code files with <code-block-group> | | Line Highlighting | Draw attention to specific lines with highlight-lines="3,5-7" | | Focus Mode | Dim non-highlighted lines with focus-mode for emphasis | | Share & Download | One-click download or open in CodePen | | Collapsible Blocks | Expandable code with "Show more" for long snippets | | Lazy Loading | Defer syntax highlighting until visible for performance | | Diff Support | Visualize code changes with +/- line highlighting | | Custom Themes | Full CSS custom property support for branding | | Light & Dark | GitHub-inspired color schemes |

Features

• 13 Web Languages - HTML, CSS, JS, JSON, YAML, PHP, and more
• Line Numbers - Optional line number display
• Filename Headers - Show file paths in the header
• Copy to Clipboard - One-click copy with visual feedback
• Word Wrap - Toggle between scroll and wrap for long lines
• Shadow DOM - Encapsulated styles that won't conflict with your app
• Accessible - ARIA labels, keyboard focus, screen reader support
• TypeScript Support - Full type definitions included

Installation

npm

npm install @profpowell/code-block

Git Submodule

Add this repository as a git submodule to your project:

git submodule add https://github.com/ProfPowell/code-block.git lib/code-block
cd lib/code-block && npm install

Then import the component:

import './lib/code-block/code-block.js';

Usage

Once imported, the <code-block> custom element is automatically registered:

<code-block language="javascript">
function greet(name) {
  return `Hello, ${name}!`;
}
</code-block>

With Custom Label

<code-block language="python" label="Data Processing">
import pandas as pd

df = pd.read_csv('data.csv')
print(df.head())
</code-block>

Dark Theme

<code-block language="css" theme="dark">
.container {
  display: grid;
  gap: 1rem;
}
</code-block>

With Line Numbers

<code-block language="javascript" show-lines>
class EventEmitter {
  constructor() {
    this.events = new Map();
  }

  on(event, callback) {
    if (!this.events.has(event)) {
      this.events.set(event, []);
    }
    this.events.get(event).push(callback);
  }
}
</code-block>

Combined Options

<code-block language="typescript" theme="dark" show-lines label="User Service">
interface User {
  id: number;
  name: string;
}

class UserService {
  async getUser(id: number): Promise<User> {
    const response = await fetch(`/api/users/${id}`);
    return response.json();
  }
}
</code-block>

Supported Languages

The component includes an optimized bundle with 13 web development languages:

| Language | Values | |----------|--------| | HTML | html, markup | | XML | xml | | XHTML | xhtml | | SVG | svg | | CSS | css | | JavaScript | javascript, js | | JSON | json | | YAML | yaml, yml | | PHP | php | | HTTP | http | | Diff | diff | | Plain Text | plaintext, text, txt | | CSV | csv |

Additional languages can be added by importing them from highlight.js.

API

Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | language | string | 'plaintext' | Programming language for highlighting | | label | string | language | Label displayed in the header | | theme | 'light' | 'dark' | 'light' | Color theme | | show-lines | boolean | false | Display line numbers | | filename | string | — | File path shown in header | | highlight-lines | string | — | Lines to highlight (e.g., "3,5-7") | | focus-mode | boolean | false | Dim non-highlighted lines for emphasis | | collapsed | boolean | false | Start in collapsed state | | max-lines | number | 10 | Lines visible when collapsed | | max-height | string | — | Max height with scrolling (e.g., "300px") | | wrap | boolean | false | Wrap long lines | | copy-text | string | 'Copy' | Custom copy button text | | copied-text | string | 'Copied!' | Custom success message | | show-share | boolean | false | Show share button | | show-download | boolean | false | Show download button | | lazy | boolean | false | Defer highlighting until visible |

Methods

| Method | Returns | Description | |--------|---------|-------------| | copyCode() | Promise<void> | Copy code to clipboard | | setCode(code) | void | Update code content | | getCode() | string | Get current code | | downloadCode() | void | Download as file | | openInCodePen() | void | Open in CodePen | | toggleCollapsed() | void | Toggle collapsed state | | render() | void | Re-render the component |

CSS Custom Properties

The component exposes 60+ CSS custom properties for full theme control. Properties marked "theme-aware" adapt automatically to light/dark mode.

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 | | --cb-border-radius | 8px | Outer container border radius | | --cb-margin | 1rem 0 | Component outer margin | | --cb-shadow | theme-aware | Box shadow on dropdown menus |

Typography

| Property | Default | Description | |----------|---------|-------------| | --cb-font-family | Consolas, Monaco, Courier New, monospace | Code font | | --cb-ui-font-family | -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif | UI font (buttons, menus) | | --cb-font-size | 0.875rem | Base code font size | | --cb-text-color | theme-aware | Default code text color | | --cb-line-height | 1.6 | Code line height |

Header

| Property | Default | Description | |----------|---------|-------------| | --cb-header-bg | theme-aware | Header bar background | | --cb-header-padding | 0.5rem 1rem | Header padding | | --cb-label-color | theme-aware | Language label and icon color | | --cb-filename-color | theme-aware | Filename text color |

Buttons

| Property | Default | Description | |----------|---------|-------------| | --cb-button-bg | theme-aware | Button background | | --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 (solid, none, etc.) | | --cb-button-radius | 4px | Border radius for copy and action buttons | | --cb-button-padding | 4px 12px | Copy button padding | | --cb-button-font-size | 0.75rem | Copy button font size | | --cb-button-hover-bg | theme-aware | Copy button hover background | | --cb-button-hover-border | theme-aware | Copy button hover border color | | --cb-action-button-hover-bg | theme-aware | Icon button hover background | | --cb-success-color | #238636 | Copied-success state color | | --cb-error-color | #da3633 | Copy-failed state color | | --cb-focus-color | theme-aware | Focus ring color |

Code Area & Line Numbers

| Property | Default | Description | |----------|---------|-------------| | --cb-code-padding | 1rem | Code area and gutter padding | | --cb-line-numbers-bg | theme-aware | Line-numbers gutter background | | --cb-line-numbers-color | theme-aware | Line-numbers text color |

Syntax Highlighting

| Property | Default (Light / Dark) | Description | |----------|----------------------|-------------| | --cb-keyword | #d73a49 / #ff7b72 | Keywords | | --cb-string | #22863a / #a5d6ff | Strings | | --cb-comment | theme-aware | Comments | | --cb-function | #6f42c1 / #d2a8ff | Function names | | --cb-number | #005cc5 / #79c0ff | Numbers | | --cb-attribute | #005cc5 / #79c0ff | HTML/XML attributes | | --cb-tag | #22863a / #7ee787 | HTML/XML tags | | --cb-meta | #e36209 / #ffa657 | Meta/preprocessor tokens | | --cb-builtin | #d73a49 / #ffa198 | Built-in names |

See docs/api.html for the complete reference including diff, expand/collapse, scrollbar, highlight, and focus-mode properties.

Example: Vanilla Breeze Integration

code-block {
  --cb-button-radius: 0;
  --cb-button-border-style: none;
  --cb-border-radius: 0;
  --cb-ui-font-family: 'Inter', sans-serif;
  --cb-font-family: 'JetBrains Mono', monospace;
}

Programmatic Usage

// Get a reference to a code block
const codeBlock = document.querySelector('code-block');

// Copy code programmatically
await codeBlock.copyCode();

// Update code content dynamically
codeBlock.setCode('const updated = true;');

// Get current code
const code = codeBlock.getCode();

// Get all supported languages (static method)
const languages = CodeBlock.getSupportedLanguages();
console.log(`Supports ${languages.length} languages`);

Server-Side Rendering (SSR)

For static sites and documentation, code blocks can be pre-rendered at build time using the SSR module. This eliminates client-side syntax highlighting and displays code instantly using Declarative Shadow DOM.

Installation

The SSR module is included in the package — no extra install needed:

import { prerenderCodeBlock, prerenderCodeBlocksInHtml } from '@profpowell/code-block/ssr'

Single Block

const html = prerenderCodeBlock({
  code: 'const x = 42;',
  language: 'javascript',
  theme: 'dark',
  showLines: true,
  filename: 'app.js',
})
// Returns complete <code-block data-ssr> with Declarative Shadow DOM

Process an HTML Page

const page = prerenderCodeBlocksInHtml(rawHtml)
// Finds all <code-block> elements and pre-renders them
// Skips blocks with src attribute or data-ssr (already processed)

SSG Integration (Cook, Eleventy, etc.)

The SSR module runs in Node.js and can be used as a build step in any static site generator:

// Example Cook plugin
import { prerenderCodeBlocksInHtml } from '@profpowell/code-block/ssr'

// Process HTML after all other transforms
file.src = prerenderCodeBlocksInHtml(file.src)

How It Works

1. Build time: prerenderCodeBlock() runs highlight.js in Node.js and generates the full shadow DOM HTML
2. Output: A <code-block data-ssr> element with <template shadowrootmode="open"> containing pre-rendered styles and highlighted code, plus a <textarea> preserving raw code for copy-to-clipboard
3. Browser: The Declarative Shadow DOM template is parsed into a real shadow root — code is visible immediately, before any JavaScript loads
4. Hydration: When the component JS loads, it detects data-ssr, skips re-rendering, and attaches interactive event listeners (copy, download, share, expand/collapse)

Options

prerenderCodeBlock() accepts all the same options as the component's HTML attributes:

| Option | Type | Default | Description | |--------|------|---------|-------------| | code | string | required | Source code to highlight | | language | string | 'plaintext' | Language for highlighting | | theme | string | 'light' | 'light' or 'dark' | | filename | string | — | Filename in header | | label | string | — | Custom label | | showLines | boolean | false | Show line numbers | | highlightLines | string | — | Lines to highlight, e.g. "2,4-6" | | focusMode | boolean | false | Dim non-highlighted lines | | collapsed | boolean | false | Start collapsed | | maxLines | number | 10 | Visible lines when collapsed | | maxHeight | string | — | Max height with scroll | | wrap | boolean | false | Word wrap | | noCopy | boolean | false | Hide copy button | | copyText | string | 'Copy' | Copy button text | | showShare | boolean | false | Show share button | | showDownload | boolean | false | Show download button |

Demo

Open demo.html in a browser to see all features in action:

• Multi-file tabbed interface
• Line highlighting
• Focus mode
• Share & download buttons
• Collapsible code blocks
• Lazy loading for performance
• Diff visualization
• CSS custom properties
• Light and dark themes
• Complete API reference

Browser Support

Works in all modern browsers that support:

• Custom Elements v1
• Shadow DOM v1
• ES6 Modules
• Clipboard API

Dependencies

• highlight.js ^11.11.1 - Syntax highlighting

License

MIT License - see LICENSE for details.