Skip to content
Kimenpre-v1documentation home
Color scheme

ki-code-block

Theme for this example
Color scheme for this example
// Load the current sample. const sample = load(3);
<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

AttributePropertyTypeDefaultDescription
copied-labelcopiedLabelstring'Copied'Polite announcement after a successful clipboard write.
copy-error-labelcopyErrorLabelstring"Couldn't copy"Polite announcement after a failed clipboard write.
copy-labelcopyLabelstring'Copy code'Accessible name of the copy button.
copyablecopyablebooleantrueShow the copy control. Set copyable="false" in HTML to hide it.
filenamefilenamestring | undefined–File name shown in the header beside the language.
highlighthighlightstring | undefined–Comma-separated lines or inclusive ranges, for example "3,5-7".
highlight-labelhighlightLabelstring'Highlighted lines'Localizable prefix for the accessible description of highlighted lines.
labellabelstring | undefined'Code'Figure and scroll area label when there is no language or filename.
languagelanguagestring | undefined–Visible language label and syntax grammar. Supports JavaScript, TypeScript and JSON.
line-numberslineNumbersbooleanfalseShow decorative one-based line numbers.
wrapwrapbooleanfalseSoft-wrap long lines within the available width.

Events

EventDetail typeDescription
ki-copyCustomEvent<{ value: string }>CopyButton reports a successful write with the original source text.
ki-copy-errorCustomEvent<void>CopyButton reports an unsuccessful clipboard write.

Slots

SlotDescription
(default)Literal source text. Escape markup in HTML or supply a text node.

CSS parts

PartDescription
codeThe monospaced source and its optional gutter.
figureFramed surface around the snippet.
headerCaption containing the language, filename and copy control.
scrollFocusable 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.

TokenDescription
--ki-code-backdrop-filterWhole backdrop filter for the figure.
--ki-code-bgSolid backing for the header and source.
--ki-code-bg-imageOptional image layer above the solid backing.
--ki-code-borderFrame and header divider.
--ki-code-border-widthWidth of the frame and header divider.
--ki-code-commentSupporting syntax ink for comments.
--ki-code-fgDefault source ink.
--ki-code-focus-colorKeyboard focus ring of the scroll area.
--ki-code-focus-widthWidth of the scroll area's focus ring.
--ki-code-font-familyTypeface for source and line numbers.
--ki-code-font-sizeCompact text size for caption and source.
--ki-code-functionSyntax ink for function names.
--ki-code-header-fgSupporting language and filename ink.
--ki-code-header-paddingCompact header inset and gap.
--ki-code-highlight-bgFill of a highlighted line.
--ki-code-highlight-markerInline rule identifying a highlighted line.
--ki-code-highlight-marker-widthWidth of the highlighted line rule.
--ki-code-keywordSyntax ink for keywords.
--ki-code-line-heightLine box height for caption and source.
--ki-code-line-numberInk for the decorative line numbers.
--ki-code-numberSyntax ink for numbers.
--ki-code-paddingInset of the source and leading caption edge.
--ki-code-radiusCorner radius of the figure.
--ki-code-stringSyntax ink for strings.
--ki-density-target-minThe 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-bodysemantic font family for typography family body.

Open ki-code-block in Storybook