@substrate-system/code-block
v0.0.4
Published
Code block web component
Readme
code-block
A web component that renders <pre><code> tags and a copy icon button.
Install
npm i -S @substrate-system/code-blockExample
import '@substrate-system/code-block'
import '@substrate-system/code-block/css'Basic
Renders a simple <pre> tag with copy icon button.
<code-block>
const answer = 42
</code-block>Example With Attributes
Use hint for copy feedback, copy-button-label for accessibility,
and a language-* class for syntax highlighting.
<code-block
hint="Copied!"
copy-button-label="Copy this example"
class="language-js"
>
const foo = 'bar'
</code-block>Syntax Highlighting with Prism
Prism is a lightweight syntax highlighting
library. It works by finding <code> elements with a language-*
class and colorizing their contents.
Since code-block forwards language-* classes to its inner
<pre> and <code> elements, Prism works out of the box.
Just load Prism's JS and CSS alongside the component.
The included example demonstrates this:
<!-- example/index.html -->
<head>
<link rel="stylesheet" href="./prism.css">
</head>
<body>
<script src="./prism.js"></script>
<script type="module" src="./index.ts"></script>
</body>// example/index.ts
import '@substrate-system/code-block'
import '@substrate-system/code-block/css'
const block = document.createElement('code-block')
block.classList.add('language-javascript')
block.textContent = `const answer = 42`
document.body.append(block)Prism detects the language-javascript class on the inner
<code> element and highlights it automatically. Any Prism
theme CSS can be swapped in for different color schemes.
API
This package exposes ESM and CommonJS via
package.json exports field.
@substrate-system/code-block
Full component (render + hydrate). It registers <code-block> when imported.
import '@substrate-system/code-block'
import '@substrate-system/code-block/css'<code-block>
const answer = 42
</code-block>@substrate-system/code-block/client
Client-only behavior (hydration only). Use this to hydrate HTML that was rendered on the server.
import { define } from '@substrate-system/code-block/client'
import '@substrate-system/code-block/css'
define()@substrate-system/code-block/html
Server-side HTML renderer.
import { CodeBlock } from '@substrate-system/code-block/html'
const html = CodeBlock({
code: 'console.log("hello")',
copyHint: true,
copyButtonLabel: 'Copy code to clipboard'
})CodeBlock.outerHTML(options, attrs) is also provided to generate the host
element wrapper.
CommonJS
require('@substrate-system/code-block')CSS
Import CSS
import '@substrate-system/code-block/css'Or minified:
import '@substrate-system/code-block/min/css'Attributes
Supported on <code-block>:
hint— Enables copy feedback hint when present (enabled by default). Usehint="false"to disable, or pass a custom string likehint="Copied!".copy-button-label— Accessible label/title for the copy icon button. Default:Copy code to clipboard.class="language-*"— Adds a language class to the inner<pre>and<code>elements for syntax highlighting (e.g.language-js,language-html). Works with any highlighting library that targetslanguage-*classes, such as Prism or highlight.js.
Example with all attributes
<code-block
hint="Copied!"
copy-button-label="Copy this snippet"
class="language-js"
>
const answer = 42
</code-block>SSR + Hydration Example
Server
import { CodeBlock } from '@substrate-system/code-block/html'
const html = CodeBlock.outerHTML({
code: 'npm i -S @substrate-system/code-block'
})Client
import { define } from '@substrate-system/code-block/client'
import '@substrate-system/code-block/css'
define()Pre-built Files
This package exposes minified JS/CSS in dist/.
Copy
cp ./node_modules/@substrate-system/code-block/dist/index.min.js ./public/code-block.min.js
cp ./node_modules/@substrate-system/code-block/dist/index.min.css ./public/code-block.cssHTML
<head>
<link rel="stylesheet" href="./code-block.css">
</head>
<body>
<code-block>console.log('hello')</code-block>
<script type="module" src="./code-block.min.js"></script>
</body>