HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
Code BlockView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA block of code with an optional name and a copy button.StableSince 0.1.0TypographyUsageimport'@fusion.dev/helix/code-block'import'@fusion.dev/helix-headless/code-block'Preview
API ReferenceRoothelix-code-blockA block of code with an optional name and a copy button.
PropTypeDescriptionaddedLinesstringDefault""The lines to mark as inserted, as numbers and ranges counted from 1, such
as 3-4. Drawn as mark-lines is, in the added color. Not for a diff.codeLabelstringDefault"Code"The name of a block that scrolls, which is a tab stop while it does.codeNameLabelstringDefault"{code}, {name}"The name of a block that scrolls, where the block has a name. {code} is
code-label and {name} the block's name.collapseLabelstringDefault"Show fewer lines"The expand button's words while the block shows every line.contextLinesnumberIn a diff, how many unchanged lines to keep beside each change. Each
longer run of unchanged lines is folded behind a button that shows it.
Unset shows every line the diff holds.copiedLabelstringDefault"Copied"The copy button's name and tooltip text after a copy.copyLabelstringDefault"Copy code"The copy button's name and tooltip text before a copy.copyNameLabelstringDefault"{copy}, {name}"The copy button's name and tooltip text before a copy, where the block
has a name. {copy} is copy-label and {name} the block's name.diffbooleanDefaultfalseWhether the content is a unified diff, drawn as the lines it changed.expandablebooleanDefaultfalseWhether a block whose height is capped takes a button that shows every
line, and fewer again.expandLabelstringDefault"Show all lines"The expand button's words while the cap hides lines.filestringThe name of the file shown, where the block holds several Code Blocks:
the label of one, or its language without one.filesLabelstringDefault"Files"The name of the file tabs, read by screen readers.hideUnchangedLabelstringDefault"{count, plural, one {Hide # unchanged line} other {Hide # unchanged lines}}"The words of a button that hides a run of unchanged lines it showed, in a
diff with context-lines. {count} is how many, and each language
writes the forms it has.highlight(code: string, language: string) => stringTurns the code into highlighted markup, which the block draws in place of
the plain text.labelstringDefault""The block's name, usually a file name, drawn in the header.languagestringDefault""The language the code is written in, such as ts or css, handed to
highlight as its second argument.lineNumbersbooleanDefaultfalseWhether the lines are numbered in a gutter beside the code.markLinesstringDefault""The lines to mark, as numbers and ranges counted from 1, such as 2, 4-6.
Each run is drawn as a band behind its lines. Not for a diff, which marks
its own changes.noCopybooleanDefaultfalseWhether to leave the copy button off.removedLinesstringDefault""The lines to mark as deleted, as numbers and ranges counted from 1. Drawn
as mark-lines is, in the removed color. Not for a diff.showUnchangedLabelstringDefault"{count, plural, one {Show # unchanged line} other {Show # unchanged lines}}"The words of a button that shows a folded run of unchanged lines, in a
diff with context-lines. {count} is how many.variant"split"How a diff's two versions are arranged. It has no effect without diff.wrapbooleanDefaultfalseWhether long lines wrap. Without it they scroll.wrapLabelstringDefault"Wrap lines"The wrap button's name, which it keeps whether it is pressed or not.wrappablebooleanDefaultfalseWhether the header has a button that wraps the lines and unwraps them. The
block draws a header for it even with no name.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The code.actionsControls for the block, in the header before the copy button.copied-iconThe copy button's icon after a copy. Defaults to a check mark.copy-iconThe copy button's icon before a copy. Defaults to a clipboard.expand-iconAn icon on the button that shows every line of a capped block, before its words.labelThe block's name in the header, such as a file icon beside the file name. Replaces label and language there, and draws the header.
EventTypeDescriptionchangeEventA file tab showed its file, whose name file now holds.helix-before-changeHelixBeforeChangeEventA file tab is about to show its file, with the file's name in detail.value. Cancelable: cancel it to keep the file shown.helix-before-toggleHelixBeforeToggleEventThe wrap button was pressed, with the wrap it asks for in detail.checked. Cancelable: cancel it to keep the lines as they are.helix-copyHelixCopyEventThe copy button put the code on the clipboard, with the text in detail.value.helix-copy-errorHelixCopyErrorEventA press on the copy button put nothing on the clipboard: the browser did not allow the write, or there was no code.helix-toggleHelixToggleEventFired after the wrap button changed wrap, with the new value in detail.checked.
PartDescriptionactionsThe box in the header that holds the actions slot, drawn while something is slotted there.addedIn a diff, a line only the new version has, an <ins>.blockThe scrolling <pre>.changedIn a diff, the words of a changed line that the line opposite it does not have, inside its text.codeThe <code> inside it.contextIn a diff, a line both versions share.copyThe copy button. It sits in the header when there is one, and beside the code otherwise.copy-buttonThe inner button.copy-liveThe copy button's live region, which speaks while the button is pending.copy-markThe clipboard icon, and the check mark that replaces it after a copy.copy-spinnerThe ring the copy button turns while it is pending.copy-textThe words on that button, trimmed to their capitals and baseline.copy-tooltip-arrowThe tooltip's arrow, which points at the copy button.copy-tooltip-arrow-bottomThe arrow while the tooltip is below the copy button, on the tooltip's top edge. Applied with copy-tooltip-arrow.copy-tooltip-arrow-leftThe arrow while the tooltip is left of the copy button, on the tooltip's right edge. Applied with copy-tooltip-arrow.copy-tooltip-arrow-rightThe arrow while the tooltip is right of the copy button, on the tooltip's left edge. Applied with copy-tooltip-arrow.copy-tooltip-arrow-topThe arrow while the tooltip is above the copy button, on the tooltip's bottom edge. Applied with copy-tooltip-arrow.copy-tooltip-surfaceThe copy button's tooltip.copy-tooltip-surface-bottomThe tooltip while it is below the copy button. Applied with copy-tooltip-surface.copy-tooltip-surface-leftThe tooltip while it is left of the copy button. Applied with copy-tooltip-surface.copy-tooltip-surface-rightThe tooltip while it is right of the copy button. Applied with copy-tooltip-surface.copy-tooltip-surface-topThe tooltip while it is above the copy button. Applied with copy-tooltip-surface.expandThe button under a capped block that shows every line, and fewer again. Drawn when expandable is set and the cap hides something.fileIn a diff, one file's header and block.file-tabOne file tab, aria-selected while its file is shown.filesThe file tabs over the blocks a block holds, where there are several.fillerIn a split diff, the empty row opposite a line the other side does not have.foldIn a diff with context-lines, the button that shows a folded run of unchanged lines, and hides it again, saying which with aria-expanded.frameThe code, and the copy button beside it where there is no header.gutterThe line numbers beside the code, shown when line-numbers is set.headerThe bar that holds the name and the copy button, shown when there is a name.hunkIn a diff, a @@ line saying where the lines under it are.labelThe block's name: its label, or its language where it has no label.markThe band behind a run of lines mark-lines, added-lines or removed-lines names. The block writes where the run is laid out into --code-block-mark-start, --code-block-mark-size, and --code-block-mark-inline-size on it. Hidden from the accessibility tree.mark-addedThe band behind a run of lines added-lines names. Applied with mark.mark-removedThe band behind a run of lines removed-lines names. Applied with mark.markerIn a diff, the +, -, or space that starts a line.newIn a split diff, the new version's <pre>.numberIn a diff, a line number. In a wrap block with line-numbers, one line's number in the gutter, which the block makes as tall as the line it numbers through --code-block-line-size.oldIn a split diff, the old version's <pre>.removedIn a diff, a line only the old version has, a <del>.splitIn a split diff, the two versions side by side.textIn a diff, a line's code.wrap-toggleThe button in the header that wraps the lines and unwraps them, drawn when wrappable is set.
CSS PropertyDescription--code-block-added-colorThe color a diff's added lines are tinted in and their + is drawn in. The success color by default.--code-block-backdropA backdrop filter for the block and its header, for a translucent background.--code-block-background-colorThe background behind the code. Set it for a block that sits on a surface other than the page background.--code-block-border-colorThe line around the block and its header.--code-block-colorThe color of the code. A highlighter's own colors win on the tokens it colors.--code-block-expand-colorThe color of the button under a capped block that shows every line.--code-block-font-familyThe typeface of the code and its line numbers. The mono face by default.--code-block-font-sizeThe size of the code and its line numbers.--code-block-gutter-colorThe color of the line numbers.--code-block-header-background-colorThe background behind the name. The default is surface-raised.--code-block-label-colorThe color of the name in the header.--code-block-line-heightThe line height of the code and its line numbers, as a number or a length.--code-block-line-sizeWritten by the block on each number in a wrap block with line-numbers: how tall the line it numbers is laid out. Do not set it.--code-block-mark-colorThe band behind the lines mark-lines names. The primary color at a wash by default.--code-block-mark-edge-colorThe edge at the start of a band behind marked lines. The primary color by default.--code-block-mark-inline-sizeWritten by the block on each mark: how wide the code is, scrolled part included. Do not set it.--code-block-mark-sizeWritten by the block on each mark: how tall its run of lines is. Do not set it.--code-block-mark-startWritten by the block on each mark: how far down the code its run of lines starts. Do not set it.--code-block-max-block-sizeThe tallest the code grows before it scrolls, or until expandable's button shows every line. The default is no limit.--code-block-radiusThe corner radius of the header's top and the block's bottom, which form one shape.--code-block-removed-colorThe color a diff's removed lines are tinted in and their - is drawn in. The danger color by default.
Custom stateDescriptionexpandedThe expand button has shown every line of a capped block.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.tabbedThe block is one of several files under another block's tabs, which name it, so it draws no name of its own.
Roothelix-headless-code-blockA block of code with an optional name and a copy button.
PropTypeDescriptionaddedLinesstringDefault""The lines to mark as inserted, as numbers and ranges counted from 1, such
as 3-4. Drawn as mark-lines is, in the added color. Not for a diff.codeLabelstringDefault"Code"The name of a block that scrolls, which is a tab stop while it does.codeNameLabelstringDefault"{code}, {name}"The name of a block that scrolls, where the block has a name. {code} is
code-label and {name} the block's name.collapseLabelstringDefault"Show fewer lines"The expand button's words while the block shows every line.contextLinesnumberIn a diff, how many unchanged lines to keep beside each change. Each
longer run of unchanged lines is folded behind a button that shows it.
Unset shows every line the diff holds.copiedLabelstringDefault"Copied"The copy button's name and tooltip text after a copy.copyLabelstringDefault"Copy code"The copy button's name and tooltip text before a copy.copyNameLabelstringDefault"{copy}, {name}"The copy button's name and tooltip text before a copy, where the block
has a name. {copy} is copy-label and {name} the block's name.diffbooleanDefaultfalseWhether the content is a unified diff, drawn as the lines it changed.expandablebooleanDefaultfalseWhether a block whose height is capped takes a button that shows every
line, and fewer again.expandLabelstringDefault"Show all lines"The expand button's words while the cap hides lines.filestringThe name of the file shown, where the block holds several Code Blocks:
the label of one, or its language without one.filesLabelstringDefault"Files"The name of the file tabs, read by screen readers.hideUnchangedLabelstringDefault"{count, plural, one {Hide # unchanged line} other {Hide # unchanged lines}}"The words of a button that hides a run of unchanged lines it showed, in a
diff with context-lines. {count} is how many, and each language
writes the forms it has.highlight(code: string, language: string) => stringTurns the code into highlighted markup, which the block draws in place of
the plain text.labelstringDefault""The block's name, usually a file name, drawn in the header.languagestringDefault""The language the code is written in, such as ts or css, handed to
highlight as its second argument.lineNumbersbooleanDefaultfalseWhether the lines are numbered in a gutter beside the code.markLinesstringDefault""The lines to mark, as numbers and ranges counted from 1, such as 2, 4-6.
Each run is drawn as a band behind its lines. Not for a diff, which marks
its own changes.noCopybooleanDefaultfalseWhether to leave the copy button off.removedLinesstringDefault""The lines to mark as deleted, as numbers and ranges counted from 1. Drawn
as mark-lines is, in the removed color. Not for a diff.showUnchangedLabelstringDefault"{count, plural, one {Show # unchanged line} other {Show # unchanged lines}}"The words of a button that shows a folded run of unchanged lines, in a
diff with context-lines. {count} is how many.variant"split"How a diff's two versions are arranged. It has no effect without diff.wrapbooleanDefaultfalseWhether long lines wrap. Without it they scroll.wrapLabelstringDefault"Wrap lines"The wrap button's name, which it keeps whether it is pressed or not.wrappablebooleanDefaultfalseWhether the header has a button that wraps the lines and unwraps them. The
block draws a header for it even with no name.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The code.actionsControls for the block, in the header before the copy button.copied-iconThe copy button's icon after a copy. Defaults to a check mark.copy-iconThe copy button's icon before a copy. Defaults to a clipboard.expand-iconAn icon on the button that shows every line of a capped block, before its words.labelThe block's name in the header, such as a file icon beside the file name. Replaces label and language there, and draws the header.
EventTypeDescriptionchangeEventA file tab showed its file, whose name file now holds.helix-before-changeHelixBeforeChangeEventA file tab is about to show its file, with the file's name in detail.value. Cancelable: cancel it to keep the file shown.helix-before-toggleHelixBeforeToggleEventThe wrap button was pressed, with the wrap it asks for in detail.checked. Cancelable: cancel it to keep the lines as they are.helix-copyHelixCopyEventThe copy button put the code on the clipboard, with the text in detail.value.helix-copy-errorHelixCopyErrorEventA press on the copy button put nothing on the clipboard: the browser did not allow the write, or there was no code.helix-toggleHelixToggleEventFired after the wrap button changed wrap, with the new value in detail.checked.
PartDescriptionactionsThe box in the header that holds the actions slot, drawn while something is slotted there.addedIn a diff, a line only the new version has, an <ins>.blockThe scrolling <pre>.changedIn a diff, the words of a changed line that the line opposite it does not have, inside its text.codeThe <code> inside it.contextIn a diff, a line both versions share.copyThe copy button. It sits in the header when there is one, and beside the code otherwise.copy-buttonThe inner button.copy-liveThe copy button's live region, which speaks while the button is pending.copy-markThe clipboard icon, and the check mark that replaces it after a copy.copy-spinnerThe ring the copy button turns while it is pending.copy-textThe words on that button, trimmed to their capitals and baseline.copy-tooltip-arrowThe tooltip's arrow, which points at the copy button.copy-tooltip-arrow-bottomThe arrow while the tooltip is below the copy button, on the tooltip's top edge. Applied with copy-tooltip-arrow.copy-tooltip-arrow-leftThe arrow while the tooltip is left of the copy button, on the tooltip's right edge. Applied with copy-tooltip-arrow.copy-tooltip-arrow-rightThe arrow while the tooltip is right of the copy button, on the tooltip's left edge. Applied with copy-tooltip-arrow.copy-tooltip-arrow-topThe arrow while the tooltip is above the copy button, on the tooltip's bottom edge. Applied with copy-tooltip-arrow.copy-tooltip-surfaceThe copy button's tooltip.copy-tooltip-surface-bottomThe tooltip while it is below the copy button. Applied with copy-tooltip-surface.copy-tooltip-surface-leftThe tooltip while it is left of the copy button. Applied with copy-tooltip-surface.copy-tooltip-surface-rightThe tooltip while it is right of the copy button. Applied with copy-tooltip-surface.copy-tooltip-surface-topThe tooltip while it is above the copy button. Applied with copy-tooltip-surface.expandThe button under a capped block that shows every line, and fewer again. Drawn when expandable is set and the cap hides something.fileIn a diff, one file's header and block.file-tabOne file tab, aria-selected while its file is shown.filesThe file tabs over the blocks a block holds, where there are several.fillerIn a split diff, the empty row opposite a line the other side does not have.foldIn a diff with context-lines, the button that shows a folded run of unchanged lines, and hides it again, saying which with aria-expanded.frameThe code, and the copy button beside it where there is no header.gutterThe line numbers beside the code, shown when line-numbers is set.headerThe bar that holds the name and the copy button, shown when there is a name.hunkIn a diff, a @@ line saying where the lines under it are.labelThe block's name: its label, or its language where it has no label.markThe band behind a run of lines mark-lines, added-lines or removed-lines names. The block writes where the run is laid out into --code-block-mark-start, --code-block-mark-size, and --code-block-mark-inline-size on it. Hidden from the accessibility tree.mark-addedThe band behind a run of lines added-lines names. Applied with mark.mark-removedThe band behind a run of lines removed-lines names. Applied with mark.markerIn a diff, the +, -, or space that starts a line.newIn a split diff, the new version's <pre>.numberIn a diff, a line number. In a wrap block with line-numbers, one line's number in the gutter, which the block makes as tall as the line it numbers through --code-block-line-size.oldIn a split diff, the old version's <pre>.removedIn a diff, a line only the old version has, a <del>.splitIn a split diff, the two versions side by side.textIn a diff, a line's code.wrap-toggleThe button in the header that wraps the lines and unwraps them, drawn when wrappable is set.
CSS PropertyDescription--code-block-line-sizeWritten by the block on each number in a wrap block with line-numbers: how tall the line it numbers is laid out. Do not set it.--code-block-mark-inline-sizeWritten by the block on each mark: how wide the code is, scrolled part included. Do not set it.--code-block-mark-sizeWritten by the block on each mark: how tall its run of lines is. Do not set it.--code-block-mark-startWritten by the block on each mark: how far down the code its run of lines starts. Do not set it.
Custom stateDescriptionexpandedThe expand button has shown every line of a capped block.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.tabbedThe block is one of several files under another block's tabs, which name it, so it draws no name of its own.
Examples
NameDescriptionBareA block with no name and no copy button, so it has no header.DiffA diff, shown as the removed lines and the added lines.ExpandableA long file capped at a height, with a button under it that shows every line and fewer again.FilesThree code blocks shown as files under tabs, one at a time.HighlightA block drawn by a highlighter of your own, whose copy is still the code as written.Line NumbersA named block with its lines numbered in a gutter that a copy leaves out.PreviewA named block of code with a copy button over it.PreviewA named block of code with a copy button over it.SplitThe old version beside the new one, each removed line opposite the line that replaced it.