HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
TerminalView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA frame around a terminal emulator that runs a shell you connect.ExperimentalSince 0.209.0MediaUsageimport'@fusion.dev/helix/terminal'import'@fusion.dev/helix-headless/terminal'Preview
API ReferenceRoothelix-terminalA frame around a terminal emulator that runs a shell you connect.
PropTypeDefaultDescriptionclearLabelstring"Clear"The clear button's label.columnsnumberThe grid's width in character cells. Set it with rows to fix the grid's size; unset, the grid fills the frame.controlsstringWhich built-in controls the header shows, as a list of find, copy,
clear, and fullscreen, or none. Absent is find clear.controlsLabelstring"Terminal controls"The name of the row of controls, read by screen readers.copiedLabelstring"Copied"What screen readers hear after a copy.copyLabelstring"Copy"The copy button's label.exitCodenumberHow the process exited, which the page sets when it does. While it is set,
the status line says it, the frame sends no input, and Restart is shown.
Clear it when a new process starts.exitedLabelstring"{code, select, 0 {The process exited.} other {The process exited with code {code}.}}"What the status line says once the process has exited. {code} is its
exit code, written as the process gave it, and code 0 is a clean exit.fallbackLabelstring"Terminal"The terminal's name where label is empty and the host has no aria-label.fillbooleanfalseCovers the container instead of taking a height of its own, for a
terminal that fills a pane. The container needs a position, such as
position: relative.findCloseLabelstring"Close find"The label of the button that closes the find bar.findControlsLabelstring"Find controls"The name of the find bar's row of buttons, read by screen readers.findLabelstring"Find"The find button's label, and the find field's name and placeholder.findNextLabelstring"Next match"The next match button's label.findPreviousLabelstring"Previous match"The previous match button's label.fullscreenLabelstring"Fill the screen"The fullscreen button's label.inputLabelstring"Terminal input"The name of the element the reader types into, which the renderer draws.labelstring""The terminal's name, in the header and for screen readers, such as the
shell or the folder it runs in. Several terminals on a page need names
that tell them apart.matchesLabelstring"{count, plural, =0 {No matches} one {{index} of # match} other {{index} of # matches}}"What the find bar says of its matches. {index} is the current match,
counting from 1, and {count} how many there are.readOnlybooleanfalseDraws the output and sends no input, with no cursor, for a transcript or
a command an agent ran. The attribute is readonly, the platform's
spelling.restartLabelstring"Restart"The Restart button's label.rowsnumberThe grid's height in lines. Set it with columns to fix the grid's size; unset, the grid fills the frame.screenReaderModebooleanfalseKeeps the grid as lines a screen reader moves through, and says new
output as it arrives. Off by default, since it costs time on every
write. Connect it to a setting your reader can turn on.separation"outlined"|"plain"How the frame stands off the page. Unset, it is outlined. plain draws
no edge or corners, for a pane that draws its own.tabHintLabelstring"Press {key} to move focus with Tab."What the terminal's input describes to a screen reader. {key} is the key that switches Tab.tabMovesFocusLabelstring"Tab moves focus. Press {key} to type Tab in the terminal."What the status line says while Tab moves focus. {key} is the key that switches it back.tabTypesLabelstring"Tab types in the terminal."What screen readers hear when Tab goes back to typing in the terminal.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The element your renderer draws the terminal in.actionsControls of your own in the header, before the built-in ones, such as a button that splits the pane.clear-iconReplaces the glyph inside the clear button.copy-iconReplaces the glyph inside the copy button.exit-actionsControls of your own beside Restart, shown once the process exits, such as a button that opens the whole log.find-actionsControls of your own in the find bar, between the count and the buttons that move between matches.find-close-iconReplaces the glyph inside the button that closes the find bar.find-iconReplaces the glyph inside the find button.find-next-iconReplaces the glyph inside the next match button.find-previous-iconReplaces the glyph inside the previous match button.fullscreen-iconReplaces the glyph inside the fullscreen button.labelThe terminal's name in the header, such as an icon beside the shell's name. Replaces label there.restart-iconReplaces the glyph inside the Restart button.
EventTypeDescriptionhelix-copyHelixCopyEventThe copy control or its key put the selection on the clipboard.helix-terminal-bellHelixTerminalBellEventThe program rang the bell. The frame flashes once.helix-terminal-inputHelixTerminalInputEventThe reader typed or pasted, with data encoded for the program. Write it to the process. Not sent while readonly, or once exit-code is set.helix-terminal-linkHelixTerminalLinkEventA link in the output was activated, with its href. Cancelable: cancel it to open the link yourself. Left alone, a web address opens in a new tab.helix-terminal-resizeHelixTerminalResizeEventThe grid changed size, with columns, rows, width, and height. Resize the process's pseudo-terminal to match.helix-terminal-restartHelixTerminalRestartEventThe Restart button was pressed after the process exited. Start a new process and clear exit-code.helix-terminal-titleHelixTerminalTitleEventThe program set its title, with title. The frame keeps its own label.
MethodTypeDescriptionattach(renderer: TerminalRenderer) => TerminalSinkAttaches what draws the terminal, and returns how it tells the frame what
happened. connectTerminal calls it; a page drawing its own terminal calls
it with its own renderer. Attaching another detaches the first.clear() => voidClears the scrollback, keeping the line the cursor is on.focus(options: FocusOptions) => voidFocuses the terminal's input, where a renderer is attached.look() => TerminalLookThe colors and the face the terminal is to be drawn in, as the
--terminal-* properties resolve where the frame is. connectTerminal
themes the renderer from it. A color nothing sets is left out, so the
renderer keeps its own: the headless tier sets none, and the styled tier
sets every one from the theme.paste(text: string) => voidInputs text as a paste does, in bracketed paste mode where the program
asked for it. It arrives as helix-terminal-input, like typed text.reset() => voidResets the emulator: its modes, its colors, and its screen.text(scope: "all" | "screen") => stringThe terminal as plain text, as the renderer drew it: the lines on screen,
or with all, every line the scrollback holds. Empty before a renderer is
attached.write(data: string | Uint8Array) => Promise<void>Writes the program's output. Resolves once the renderer has parsed it,
which is how a page pauses a process that writes faster than the
terminal draws. Output written before a renderer is attached is held and
written first.
PartDescriptionactionsThe actions slot, first in the header's toolbar.clearThe button that clears the scrollback.clear-buttonThe clear button's inner button.clear-liveThe clear button's live region, which speaks while the button is pending.clear-spinnerThe ring the clear button turns while it is pending.clear-textThe box the clear button's icon sits in.controlsThe toolbar at the end of the header: your actions, then the built-in buttons, one tab stop that the arrows move along.controls-toolbarThe box inside the header's toolbar that lays its buttons out.copyThe button that copies the selection. Disabled while nothing is selected.copy-buttonThe copy button's inner button.copy-liveThe copy button's live region, which speaks while the button is pending.copy-spinnerThe ring the copy button turns while it is pending.copy-textThe box the copy button's icon sits in.exit-actionsThe exit-actions slot, beside Restart in the status line.findThe button that opens and closes the find bar. Expanded while it is open.find-actionsThe find-actions slot, first in the find bar's toolbar.find-barThe bar under the header where the reader searches the output.find-buttonThe find button's inner button.find-closeThe button that closes the find bar.find-close-buttonThe find bar's close button's inner button.find-close-liveThe find bar's close button's live region, which speaks while the button is pending.find-close-spinnerThe ring the find bar's close button turns while it is pending.find-close-textThe box the find bar's close button's icon sits in.find-controlsThe toolbar at the end of the find bar: your find actions, then the buttons that move between matches and close the bar.find-controls-toolbarThe box inside the find bar's toolbar that lays its buttons out.find-countWhich match is current and how many there are, such as "3 of 12 matches".find-fieldThe search field in the find bar.find-liveThe find button's live region, which speaks while the button is pending.find-nextThe button that moves to the next match.find-next-buttonThe next match button's inner button.find-next-liveThe next match button's live region, which speaks while the button is pending.find-next-spinnerThe ring the next match button turns while it is pending.find-next-textThe box the next match button's icon sits in.find-previousThe button that moves to the previous match.find-previous-buttonThe previous match button's inner button.find-previous-liveThe previous match button's live region, which speaks while the button is pending.find-previous-spinnerThe ring the previous match button turns while it is pending.find-previous-textThe box the previous match button's icon sits in.find-spinnerThe ring the find button turns while it is pending.find-textThe box the find button's icon sits in.fullscreenThe button that makes the terminal fill the screen. Pressed while it does.fullscreen-buttonThe fullscreen button's inner button.fullscreen-liveThe fullscreen button's live region, which speaks while the button is pending.fullscreen-spinnerThe ring the fullscreen button turns while it is pending.fullscreen-textThe box the fullscreen button's icon sits in.headerThe strip above the terminal, with its name, your actions, and the controls.labelThe terminal's name in the header.liveWhat screen readers hear after the frame acts: a match count, a copy, or a change to what Tab does. Visually hidden in the styled tier.regionThe named group the terminal sits in.restartThe button in the status line that asks for a new process after the last one exited.restart-buttonThe Restart button's inner button.restart-liveThe Restart button's live region, which speaks while the button is pending.restart-spinnerThe ring the Restart button turns while it is pending.restart-textThe Restart button's label.statusThe line under the terminal that says the process exited, or that Tab moves focus.viewportThe box the terminal is drawn in.
CSS PropertyDescription--terminal-active-match-background-colorThe ground of the current match of a search.--terminal-active-match-border-colorThe edge of the current match of a search.--terminal-ansi-blackANSI black, which codes 30 and 40 draw.--terminal-ansi-blueANSI blue, which codes 34 and 44 draw.--terminal-ansi-bright-blackANSI bright black, which codes 90 and 100 draw.--terminal-ansi-bright-blueANSI bright blue, which codes 94 and 104 draw.--terminal-ansi-bright-cyanANSI bright cyan, which codes 96 and 106 draw.--terminal-ansi-bright-greenANSI bright green, which codes 92 and 102 draw.--terminal-ansi-bright-magentaANSI bright magenta, which codes 95 and 105 draw.--terminal-ansi-bright-redANSI bright red, which codes 91 and 101 draw.--terminal-ansi-bright-whiteANSI bright white, which codes 97 and 107 draw.--terminal-ansi-bright-yellowANSI bright yellow, which codes 93 and 103 draw.--terminal-ansi-cyanANSI cyan, which codes 36 and 46 draw.--terminal-ansi-greenANSI green, which codes 32 and 42 draw.--terminal-ansi-magentaANSI magenta, which codes 35 and 45 draw.--terminal-ansi-redANSI red, which codes 31 and 41 draw.--terminal-ansi-whiteANSI white, which codes 37 and 47 draw.--terminal-ansi-yellowANSI yellow, which codes 33 and 43 draw.--terminal-background-colorThe ground of the grid.--terminal-block-sizeThe frame's height, as a length. Ignored with fill, where the container decides it.--terminal-border-colorThe edge around the frame and the rules inside it.--terminal-colorThe text of the grid where the program sets no color.--terminal-cursor-colorThe cursor.--terminal-font-familyThe face of the grid. Defaults to the monospaced face.--terminal-font-sizeThe size of the grid's text. Defaults to the small text step.--terminal-header-background-colorThe fill of the header, the find bar, and the status line.--terminal-match-background-colorThe ground of every match of a search but the current one.--terminal-paddingThe space between the frame's edge and the grid.--terminal-radiusThe frame's corners.--terminal-scrollbar-thumb-colorThe grid's scrollbar.--terminal-selection-background-colorThe ground of selected text. See-through, so the text keeps its color.
Custom stateDescriptionbellThe program rang the bell, held for a moment for a visual bell.exitedThe process has exited, by exit-code.find-openThe find bar is open.fullscreenThe terminal fills the screen.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.tab-moves-focusTab moves focus out of the terminal, after Control+M.
Roothelix-headless-terminalA frame around a terminal emulator that runs a shell you connect.
PropTypeDefaultDescriptionclearLabelstring"Clear"The clear button's label.columnsnumberThe grid's width in character cells. Set it with rows to fix the grid's size; unset, the grid fills the frame.controlsstringWhich built-in controls the header shows, as a list of find, copy,
clear, and fullscreen, or none. Absent is find clear.controlsLabelstring"Terminal controls"The name of the row of controls, read by screen readers.copiedLabelstring"Copied"What screen readers hear after a copy.copyLabelstring"Copy"The copy button's label.exitCodenumberHow the process exited, which the page sets when it does. While it is set,
the status line says it, the frame sends no input, and Restart is shown.
Clear it when a new process starts.exitedLabelstring"{code, select, 0 {The process exited.} other {The process exited with code {code}.}}"What the status line says once the process has exited. {code} is its
exit code, written as the process gave it, and code 0 is a clean exit.fallbackLabelstring"Terminal"The terminal's name where label is empty and the host has no aria-label.findCloseLabelstring"Close find"The label of the button that closes the find bar.findControlsLabelstring"Find controls"The name of the find bar's row of buttons, read by screen readers.findLabelstring"Find"The find button's label, and the find field's name and placeholder.findNextLabelstring"Next match"The next match button's label.findPreviousLabelstring"Previous match"The previous match button's label.fullscreenLabelstring"Fill the screen"The fullscreen button's label.inputLabelstring"Terminal input"The name of the element the reader types into, which the renderer draws.labelstring""The terminal's name, in the header and for screen readers, such as the
shell or the folder it runs in. Several terminals on a page need names
that tell them apart.matchesLabelstring"{count, plural, =0 {No matches} one {{index} of # match} other {{index} of # matches}}"What the find bar says of its matches. {index} is the current match,
counting from 1, and {count} how many there are.readOnlybooleanfalseDraws the output and sends no input, with no cursor, for a transcript or
a command an agent ran. The attribute is readonly, the platform's
spelling.restartLabelstring"Restart"The Restart button's label.rowsnumberThe grid's height in lines. Set it with columns to fix the grid's size; unset, the grid fills the frame.screenReaderModebooleanfalseKeeps the grid as lines a screen reader moves through, and says new
output as it arrives. Off by default, since it costs time on every
write. Connect it to a setting your reader can turn on.tabHintLabelstring"Press {key} to move focus with Tab."What the terminal's input describes to a screen reader. {key} is the key that switches Tab.tabMovesFocusLabelstring"Tab moves focus. Press {key} to type Tab in the terminal."What the status line says while Tab moves focus. {key} is the key that switches it back.tabTypesLabelstring"Tab types in the terminal."What screen readers hear when Tab goes back to typing in the terminal.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The element your renderer draws the terminal in.actionsControls of your own in the header, before the built-in ones, such as a button that splits the pane.clear-iconReplaces the glyph inside the clear button.copy-iconReplaces the glyph inside the copy button.exit-actionsControls of your own beside Restart, shown once the process exits, such as a button that opens the whole log.find-actionsControls of your own in the find bar, between the count and the buttons that move between matches.find-close-iconReplaces the glyph inside the button that closes the find bar.find-iconReplaces the glyph inside the find button.find-next-iconReplaces the glyph inside the next match button.find-previous-iconReplaces the glyph inside the previous match button.fullscreen-iconReplaces the glyph inside the fullscreen button.labelThe terminal's name in the header, such as an icon beside the shell's name. Replaces label there.restart-iconReplaces the glyph inside the Restart button.
EventTypeDescriptionhelix-copyHelixCopyEventThe copy control or its key put the selection on the clipboard.helix-terminal-bellHelixTerminalBellEventThe program rang the bell. The frame flashes once.helix-terminal-inputHelixTerminalInputEventThe reader typed or pasted, with data encoded for the program. Write it to the process. Not sent while readonly, or once exit-code is set.helix-terminal-linkHelixTerminalLinkEventA link in the output was activated, with its href. Cancelable: cancel it to open the link yourself. Left alone, a web address opens in a new tab.helix-terminal-resizeHelixTerminalResizeEventThe grid changed size, with columns, rows, width, and height. Resize the process's pseudo-terminal to match.helix-terminal-restartHelixTerminalRestartEventThe Restart button was pressed after the process exited. Start a new process and clear exit-code.helix-terminal-titleHelixTerminalTitleEventThe program set its title, with title. The frame keeps its own label.
MethodTypeDescriptionattach(renderer: TerminalRenderer) => TerminalSinkAttaches what draws the terminal, and returns how it tells the frame what
happened. connectTerminal calls it; a page drawing its own terminal calls
it with its own renderer. Attaching another detaches the first.clear() => voidClears the scrollback, keeping the line the cursor is on.focus(options: FocusOptions) => voidFocuses the terminal's input, where a renderer is attached.look() => TerminalLookThe colors and the face the terminal is to be drawn in, as the
--terminal-* properties resolve where the frame is. connectTerminal
themes the renderer from it. A color nothing sets is left out, so the
renderer keeps its own: the headless tier sets none, and the styled tier
sets every one from the theme.paste(text: string) => voidInputs text as a paste does, in bracketed paste mode where the program
asked for it. It arrives as helix-terminal-input, like typed text.reset() => voidResets the emulator: its modes, its colors, and its screen.text(scope: "all" | "screen") => stringThe terminal as plain text, as the renderer drew it: the lines on screen,
or with all, every line the scrollback holds. Empty before a renderer is
attached.write(data: string | Uint8Array) => Promise<void>Writes the program's output. Resolves once the renderer has parsed it,
which is how a page pauses a process that writes faster than the
terminal draws. Output written before a renderer is attached is held and
written first.
PartDescriptionactionsThe actions slot, first in the header's toolbar.clearThe button that clears the scrollback.clear-buttonThe clear button's inner button.clear-liveThe clear button's live region, which speaks while the button is pending.clear-spinnerThe ring the clear button turns while it is pending.clear-textThe box the clear button's icon sits in.controlsThe toolbar at the end of the header: your actions, then the built-in buttons, one tab stop that the arrows move along.controls-toolbarThe box inside the header's toolbar that lays its buttons out.copyThe button that copies the selection. Disabled while nothing is selected.copy-buttonThe copy button's inner button.copy-liveThe copy button's live region, which speaks while the button is pending.copy-spinnerThe ring the copy button turns while it is pending.copy-textThe box the copy button's icon sits in.exit-actionsThe exit-actions slot, beside Restart in the status line.findThe button that opens and closes the find bar. Expanded while it is open.find-actionsThe find-actions slot, first in the find bar's toolbar.find-barThe bar under the header where the reader searches the output.find-buttonThe find button's inner button.find-closeThe button that closes the find bar.find-close-buttonThe find bar's close button's inner button.find-close-liveThe find bar's close button's live region, which speaks while the button is pending.find-close-spinnerThe ring the find bar's close button turns while it is pending.find-close-textThe box the find bar's close button's icon sits in.find-controlsThe toolbar at the end of the find bar: your find actions, then the buttons that move between matches and close the bar.find-controls-toolbarThe box inside the find bar's toolbar that lays its buttons out.find-countWhich match is current and how many there are, such as "3 of 12 matches".find-fieldThe search field in the find bar.find-liveThe find button's live region, which speaks while the button is pending.find-nextThe button that moves to the next match.find-next-buttonThe next match button's inner button.find-next-liveThe next match button's live region, which speaks while the button is pending.find-next-spinnerThe ring the next match button turns while it is pending.find-next-textThe box the next match button's icon sits in.find-previousThe button that moves to the previous match.find-previous-buttonThe previous match button's inner button.find-previous-liveThe previous match button's live region, which speaks while the button is pending.find-previous-spinnerThe ring the previous match button turns while it is pending.find-previous-textThe box the previous match button's icon sits in.find-spinnerThe ring the find button turns while it is pending.find-textThe box the find button's icon sits in.fullscreenThe button that makes the terminal fill the screen. Pressed while it does.fullscreen-buttonThe fullscreen button's inner button.fullscreen-liveThe fullscreen button's live region, which speaks while the button is pending.fullscreen-spinnerThe ring the fullscreen button turns while it is pending.fullscreen-textThe box the fullscreen button's icon sits in.headerThe strip above the terminal, with its name, your actions, and the controls.labelThe terminal's name in the header.liveWhat screen readers hear after the frame acts: a match count, a copy, or a change to what Tab does. Visually hidden in the styled tier.regionThe named group the terminal sits in.restartThe button in the status line that asks for a new process after the last one exited.restart-buttonThe Restart button's inner button.restart-liveThe Restart button's live region, which speaks while the button is pending.restart-spinnerThe ring the Restart button turns while it is pending.restart-textThe Restart button's label.statusThe line under the terminal that says the process exited, or that Tab moves focus.viewportThe box the terminal is drawn in.
CSS PropertyDescription--terminal-active-match-background-colorThe ground of the current match of a search.--terminal-active-match-border-colorThe edge of the current match of a search.--terminal-ansi-blackANSI black, which codes 30 and 40 draw.--terminal-ansi-blueANSI blue, which codes 34 and 44 draw.--terminal-ansi-bright-blackANSI bright black, which codes 90 and 100 draw.--terminal-ansi-bright-blueANSI bright blue, which codes 94 and 104 draw.--terminal-ansi-bright-cyanANSI bright cyan, which codes 96 and 106 draw.--terminal-ansi-bright-greenANSI bright green, which codes 92 and 102 draw.--terminal-ansi-bright-magentaANSI bright magenta, which codes 95 and 105 draw.--terminal-ansi-bright-redANSI bright red, which codes 91 and 101 draw.--terminal-ansi-bright-whiteANSI bright white, which codes 97 and 107 draw.--terminal-ansi-bright-yellowANSI bright yellow, which codes 93 and 103 draw.--terminal-ansi-cyanANSI cyan, which codes 36 and 46 draw.--terminal-ansi-greenANSI green, which codes 32 and 42 draw.--terminal-ansi-magentaANSI magenta, which codes 35 and 45 draw.--terminal-ansi-redANSI red, which codes 31 and 41 draw.--terminal-ansi-whiteANSI white, which codes 37 and 47 draw.--terminal-ansi-yellowANSI yellow, which codes 33 and 43 draw.--terminal-background-colorThe ground of the grid.--terminal-colorThe text of the grid where the program sets no color.--terminal-cursor-colorThe cursor.--terminal-match-background-colorThe ground of every match of a search but the current one.--terminal-scrollbar-thumb-colorThe grid's scrollbar.--terminal-selection-background-colorThe ground of selected text. See-through, so the text keeps its color.
Custom stateDescriptionbellThe program rang the bell, held for a moment for a visual bell.exitedThe process has exited, by exit-code.find-openThe find bar is open.fullscreenThe terminal fills the screen.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.tab-moves-focusTab moves focus out of the terminal, after Control+M.
ExamplesNameDescriptionAnsi ColorsThe sixteen ANSI colors as your theme draws them, as text and as grounds.ExitedA terminal whose process exited, with the status line saying how and a Restart button that starts another.In A PaneA terminal that fills one pane of a Splitter, flush with its edges, under a session, with a button of your own in its header.PreviewA terminal running a shell, with its name in the header and the find and clear controls.PreviewA terminal running a shell, with its name in the header and the find and clear controls.TranscriptA command an agent ran, shown read-only, with find and copy for its output.