ki-code-block
@kimen/elements/ki-code-block- Source
- Agent reference
<ki-code-block language="ts" filename="main.ts" line-numbers highlight="2">// Load the current sample.const sample = load(3);</ki-code-block>Supply the snippet as a plain text child. Escape HTML markup in static
examples or assign textContent when you create the element in JavaScript.
JavaScript, TypeScript and JSON have syntax colors. Other language labels
display the source as plain text.
Use line-numbers to show a gutter and highlight="3,5-7" for one-based
lines or inclusive ranges. Long lines scroll by default. Add wrap to wrap
them. The scroll area is a Tab stop, and the arrow keys scroll overflowing
code. The language and filename name the figure and scroll area. The scroll
area describes highlighted lines, and line numbers are hidden from assistive
technology.
CopyButton copies the original whitespace and reports the outcome. Set
copyable="false" to hide the button. Localize the figure’s fallback name
with label, the description prefix with highlight-label and the copy
control with copy-label, copied-label and copy-error-label.
Listen for ki-copy to receive the original source in detail.value, or
ki-copy-error to respond to a failed write. A guarded surface can bind a
declared action to ki-copy.
API reference
When to use: display a multiline example, generated code or a tool result that readers should be able to inspect and copy.
When not to use: when the reader should edit the source or when the code belongs inline in a sentence. Use an editor or a native inline code element.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
copied-label | copiedLabel | string | 'Copied' | Polite announcement after a successful clipboard write. |
copy-error-label | copyErrorLabel | string | "Couldn't copy" | Polite announcement after a failed clipboard write. |
copy-label | copyLabel | string | 'Copy code' | Accessible name of the copy button. |
copyable | copyable | boolean | true | Show the copy control. Set copyable="false" in HTML to hide it. |
filename | filename | string | undefined | – | File name shown in the header beside the language. |
highlight | highlight | string | undefined | – | Comma-separated lines or inclusive ranges, for example "3,5-7". |
highlight-label | highlightLabel | string | 'Highlighted lines' | Localizable prefix for the accessible description of highlighted lines. |
label | label | string | undefined | 'Code' | Figure and scroll area label when there is no language or filename. |
language | language | string | undefined | – | Visible language label and syntax grammar. Supports JavaScript, TypeScript and JSON. |
line-numbers | lineNumbers | boolean | false | Show decorative one-based line numbers. |
wrap | wrap | boolean | false | Soft-wrap long lines within the available width. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-copy | CustomEvent<{ value: string }> | CopyButton reports a successful write with the original source text. |
ki-copy-error | CustomEvent<void> | CopyButton reports an unsuccessful clipboard write. |
Slots
| Slot | Description |
|---|---|
| (default) | Literal source text. Escape markup in HTML or supply a text node. |
CSS parts
| Part | Description |
|---|---|
code | The monospaced source and its optional gutter. |
figure | Framed surface around the snippet. |
header | Caption containing the language, filename and copy control. |
scroll | Focusable native code scroll area. |
CSS custom properties
The public styling contract of ki-code-block: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-code-backdrop-filter | Whole backdrop filter for the figure. |
--ki-code-bg | Solid backing for the header and source. |
--ki-code-bg-image | Optional image layer above the solid backing. |
--ki-code-border | Frame and header divider. |
--ki-code-border-width | Width of the frame and header divider. |
--ki-code-comment | Supporting syntax ink for comments. |
--ki-code-fg | Default source ink. |
--ki-code-focus-color | Keyboard focus ring of the scroll area. |
--ki-code-focus-width | Width of the scroll area's focus ring. |
--ki-code-font-family | Typeface for source and line numbers. |
--ki-code-font-size | Compact text size for caption and source. |
--ki-code-function | Syntax ink for function names. |
--ki-code-header-fg | Supporting language and filename ink. |
--ki-code-header-padding | Compact header inset and gap. |
--ki-code-highlight-bg | Fill of a highlighted line. |
--ki-code-highlight-marker | Inline rule identifying a highlighted line. |
--ki-code-highlight-marker-width | Width of the highlighted line rule. |
--ki-code-keyword | Syntax ink for keywords. |
--ki-code-line-height | Line box height for caption and source. |
--ki-code-line-number | Ink for the decorative line numbers. |
--ki-code-number | Syntax ink for numbers. |
--ki-code-padding | Inset of the source and leading caption edge. |
--ki-code-radius | Corner radius of the figure. |
--ki-code-string | Syntax ink for strings. |
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-typography-family-body | semantic font family for typography family body. |