Iciclecreek.Avalonia.Terminal
4.1.4
dotnet add package Iciclecreek.Avalonia.Terminal --version 4.1.4
NuGet\Install-Package Iciclecreek.Avalonia.Terminal -Version 4.1.4
<PackageReference Include="Iciclecreek.Avalonia.Terminal" Version="4.1.4" />
<PackageVersion Include="Iciclecreek.Avalonia.Terminal" Version="4.1.4" />
<PackageReference Include="Iciclecreek.Avalonia.Terminal" />
paket add Iciclecreek.Avalonia.Terminal --version 4.1.4
#r "nuget: Iciclecreek.Avalonia.Terminal, 4.1.4"
#:package Iciclecreek.Avalonia.Terminal@4.1.4
#addin nuget:?package=Iciclecreek.Avalonia.Terminal&version=4.1.4
#tool nuget:?package=Iciclecreek.Avalonia.Terminal&version=4.1.4
![]()
Iciclecreek.Avalonia.Terminal For Avalonia 12.x

A cross-platform XTerm terminal emulator control for Avalonia UI applications.
Introduction
Iciclecreek.Avalonia.Terminal provides Avalonia controls for embedding a fully-featured terminal emulator in your cross-platform desktop applications. Built on top of XTerm.NET for terminal emulation and Porta.Pty for pseudo-terminal support, it offers:
- Full XTerm-compatible terminal emulation
- Cross-platform support (Windows, Linux, macOS)
- Scrollback buffer with configurable size
- Text selection and clipboard support
- Terminal window manipulation commands (resize, move, minimize, maximize, etc.)
- Dynamic title updates from terminal escape sequences
- Customizable fonts, colors, and styling
- Graphics
Installation
Install via NuGet Package Manager:
dotnet add package Iciclecreek.Avalonia.Terminal
Or via the Package Manager Console in Visual Studio:
Install-Package Iciclecreek.Avalonia.Terminal
Compliance

Usage
There are 2 Avalonia Controls:
- TerminalControl - allows you to embed a terminal anywhere in xaml markup
- TerminalWindow - a popup window with a terminal control in it.
TerminalControl
TerminalControl is a templated control that provides a terminal view with an integrated scrollbar. Use this when you want to embed a terminal within your own window or layout.
XAML:
<Window xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:terminal="using:Iciclecreek.Terminal"
x:Class="MyApp.MainWindow">
<terminal:TerminalControl x:Name="Terminal"
FontFamily="Cascadia Mono"
FontSize="14"
BufferSize="1000"
ProcessExited="OnProcessExited"/>
</Window>
Code-behind:
using Avalonia.Controls;
using Iciclecreek.Terminal;
public partial class MainWindow : Window
{
public MainWindow()
{
InitializeComponent();
}
private void OnProcessExited(object? sender, ProcessExitedEventArgs e)
{
// Handle process exit (e.g., close window)
Close();
}
}
Properties:
| Property | Type | Default | Description |
|---|---|---|---|
Process |
string |
cmd.exe (Windows) / bash (Unix) |
The shell or process to launch |
ProcessArgs |
IList<string> |
Empty | Command-line arguments for the process |
StartingDirectory |
string? |
Current working directory | The initial working directory used when launching the PTY process |
CurrentDirectory |
string? |
Read-only | The current working directory reported by the running terminal session via OSC 7 |
ExitCode |
int |
Read-only | The exit code of the launched process after it has terminated |
Pid |
int |
Read-only | The operating system process identifier of the launched terminal process |
BufferSize |
int |
1000 |
Scrollback buffer size (number of lines) |
VerbatimCommandLine |
bool |
false |
When false, each entry in ProcessArgs reaches the process as a distinct argument, quoted so it arrives exactly as written. Set true to join the entries into one command line and let the process parse it itself. Windows only — Unix passes an argument vector to exec, so there is nothing to build |
EnvironmentVariables |
IDictionary<string,string>? |
null |
Extra environment variables for the launched process. Merged into the environment it would otherwise inherit, not substituted for it, so setting one variable does not cost you PATH. TERM is already set to xterm-256color by the PTY layer |
FontFamily |
FontFamily |
Monospace stack | Terminal font family. Defaults to Cascadia Mono and friends, falling back to the platform's generic monospace — a terminal must not inherit a proportional UI font. Set it to override |
FontSize |
double |
Inherited | Terminal font size |
Foreground |
IBrush |
White |
Default text color |
Background |
IBrush |
Black |
Terminal background color |
SelectionBrush |
IBrush |
Semi-transparent blue | Text selection highlight color |
TextDecorations |
TextDecorationLocation? |
null |
Text decorations applied to terminal text |
Ligatures |
bool |
false |
Draw the font's programming ligatures (->, =>, != joining, in Fira Code, Cascadia Code and friends). Opt-in; fonts without ligatures are unaffected either way |
CursorColor |
Color |
White |
Cursor color |
CursorStyle |
CursorStyle |
Bar |
Cursor shape — Bar, Block or Underline |
CursorBlink |
bool |
true |
Whether the cursor blinks |
CursorBlinkRate |
int |
530 |
Blink interval in milliseconds |
ViewportY |
int |
Live | Absolute line index of the top of the viewport. Settable, to drive your own scrollbar |
MaxScrollback |
int |
Read-only | Largest valid ViewportY — total buffer lines minus visible lines |
ViewportLines |
int |
Read-only | Number of lines visible |
Zoom |
double |
1.0 |
Multiplier on FontSize, 0.5–3.0. View state driven by the zoom shortcuts; FontSize itself is left alone so a host binding to it keeps working |
ShortcutMode |
ShortcutMode |
Terminal |
Which convention the contested keys follow: Terminal (Ctrl+A/V/X belong to the program), Desktop (they select all, paste and cut) or None (no keyboard shortcuts at all). See Keyboard shortcuts |
ClearSelectionOnTyping |
bool |
true |
Whether typing drops a mouse selection. Set false to keep it while typing; a Shift+arrow selection over the input is still replaced by what is typed |
LinkClickModifiers |
KeyModifiers |
Control |
The modifier keys a left click on a link must hold to raise UrlClicked. Every one named must be down. A macOS host will usually want Meta (Cmd) |
LinkHighlightRequiresModifier |
bool |
false |
Underline a link, show the hand cursor and report it in HoveredLink only while LinkClickModifiers are held. Pressing or releasing the modifier updates it without moving the pointer |
DetectUrls |
bool |
true |
Treat text that looks like a URL as a link. Links a program declares with OSC 8 are unaffected |
HoveredLink |
TerminalLink? |
Read-only | The link highlighted under the pointer: its Url, whether it came from OSC 8 (FromSequence), and the cells it covers (Segments) |
IsAlternateBuffer |
bool |
Read-only | True while a full-screen application (vim, htop, less) is using the alternate screen buffer |
IsLive |
bool |
Read-only | True while a PTY is attached and its process has not exited |
ShellState |
ShellState |
Read-only | Where the shell is, from its OSC 133 shell integration marks: Unknown, Prompt, Input or Running. Running means a command owns the terminal, which is when closing it should ask first. A shell without integration stays Unknown |
Methods:
| Method | Description |
|---|---|
LaunchProcess() |
Launches the configured Process with the current ProcessArgs and StartingDirectory |
LaunchProcess(string? startingDirectory, string process, params string[] args) |
Convenience overload that sets StartingDirectory, Process, and ProcessArgs, then launches the process |
Kill() |
Terminates the running terminal process |
SendInputAsync(string text, CancellationToken) |
Sends text to the running process as if typed. Sent verbatim, so append \r to submit a command: SendInputAsync("ls -la\r"). Does nothing when no process is running |
CopyAsync() |
Copies the selection to the clipboard. Returns false when nothing was selected |
PasteAsync() |
Pastes clipboard text into the terminal |
SelectInputAsync() |
Selects the shell's editable input — what has been typed at the prompt. Returns false when there is none |
ZoomIn() / ZoomOut() / ResetZoom() |
Step Zoom by a tenth, or put it back to 1.0 |
ScrollPageUp() / ScrollPageDown() |
Move the viewport a screenful through the scrollback |
ScrollToTop() / ScrollToBottom() |
Jump to the oldest line, or back to the live output |
AttachConnection(IPtyConnection) |
Drives the terminal from a PTY the caller owns. Throws if the template has not been applied |
DetachConnection() |
Stops following the current connection and hands it back, without stopping the process |
WaitForExit(int ms) |
Waits for the terminal process to exit or for the specified timeout to elapse |
Events:
| Event | Description |
|---|---|
ProcessExited |
Raised when the PTY process exits. The handler receives ProcessExitedEventArgs with the process ExitCode. |
ShellStateChanged |
Raised on the UI thread when ShellState changes. ShellStateChangedEventArgs carries OldState, NewState and, when a 133;D ended a command, its ExitCode. A bubbling routed event, so a handler on TerminalControl or TerminalWindow sees it too. |
ClipboardFailed |
Raised when a clipboard operation with no caller to throw to failed, which on Windows happens while another process has the clipboard open: a copy, cut or paste from a key press or mouse click, or the running program's own request. Check Operation before telling the user, because a program can make requests in the background. CopyAsync, CutAsync and PasteAsync throw to their caller instead. |
UrlClicked |
Raised when a link is clicked with LinkClickModifiers held. The terminal never opens it; UrlClickedEventArgs carries the Url and whether it came from OSC 8, so the host can check the scheme first. |
PasteRequested |
Raised before anything is pasted, from PasteAsync, the paste keys and right-click alike. The handler sees the clipboard's text in PasteRequestedEventArgs and can replace it, set Cancel, or hold the paste with GetDeferral() while it asks the user. The terminal does its own bracketing and paste announcement afterwards, so Text is the bare text. |
HoveredLinkChanged |
Raised when HoveredLink changes: the pointer moved onto a link, from one link to another, or off one. Once per change, never for moves within a link. |
TerminalWindow
TerminalWindow is a complete window implementation that automatically handles terminal events like title changes and window manipulation commands. Use this when you want a standalone terminal window.
XAML:
<terminal:TerminalWindow xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:terminal="using:Iciclecreek.Terminal"
x:Class="MyApp.TerminalWindow"
Title="Terminal"
Width="800"
Height="600"
FontFamily="Consolas"
FontSize="12"
Background="Black"
Foreground="White"
CloseOnProcessExit="True"
UpdateTitleFromTerminal="True"/>
Or create programmatically:
using Iciclecreek.Terminal;
var terminalWindow = new TerminalWindow
{
Title = "My Terminal",
Width = 800,
Height = 600,
FontFamily = new FontFamily("Cascadia Mono"),
FontSize = 14,
StartingDirectory = Environment.CurrentDirectory,
Process = "pwsh.exe", // PowerShell Core
ProcessArgs = new[] { "-NoLogo" },
CloseOnProcessExit = true
};
terminalWindow.Show();
Methods:
| Method | Description |
|---|---|
LaunchProcess() |
Launches the configured Process with the current ProcessArgs and StartingDirectory |
LaunchProcess(string? startingDirectory, string process, params string[] args) |
Convenience overload that sets StartingDirectory, Process, and ProcessArgs, then launches the process |
Kill() |
Terminates the running terminal process |
SendInputAsync(string text, CancellationToken) |
Sends text to the running process as if typed. Sent verbatim, so append \r to submit a command: SendInputAsync("ls -la\r"). Does nothing when no process is running |
CopyAsync() |
Copies the selection to the clipboard. Returns false when nothing was selected |
PasteAsync() |
Pastes clipboard text into the terminal |
AttachConnection(IPtyConnection) |
Drives the terminal from a PTY the caller owns. Throws if the template has not been applied |
DetachConnection() |
Stops following the current connection and hands it back, without stopping the process |
WaitForExit(int ms) |
Waits for the terminal process to exit or for the specified timeout to elapse |
Additional Properties (beyond TerminalControl):
| Property | Type | Default | Description |
|---|---|---|---|
ExitCode |
int |
Read-only | The exit code of the launched process after it has terminated |
Pid |
int |
Read-only | The operating system process identifier of the launched terminal process |
CloseOnProcessExit |
bool |
true |
Automatically close the window when the process exits |
UpdateTitleFromTerminal |
bool |
true |
Update window title from terminal escape sequences |
Window manipulation commands from the terminal (resize, move, minimize, maximize, raise, lower, fullscreen) are always handled. Handle the corresponding bubbling event from TerminalView and mark it Handled to suppress the default behaviour for any of them.
TerminalWindow exposes everything TerminalControl does, forwarding each member to the control it hosts, and TerminalControl in turn exposes everything TerminalView does. A test walks all three surfaces by reflection and fails if they drift apart, so a member added to the view without a forwarder breaks the build rather than going unnoticed.
Events:
| Event | Description |
|---|---|
ProcessExited |
Raised when the PTY process exits. The handler receives ProcessExitedEventArgs with the process ExitCode. If CloseOnProcessExit is true, the event is raised before the window closes. |
ClipboardFailed |
Raised when a clipboard operation with no caller to throw to failed, which on Windows happens while another process has the clipboard open: a copy, cut or paste from a key press or mouse click, or the running program's own request. Check Operation before telling the user, because a program can make requests in the background. CopyAsync, CutAsync and PasteAsync throw to their caller instead. |
UrlClicked |
Raised when a link is clicked with LinkClickModifiers held. The terminal never opens it; UrlClickedEventArgs carries the Url and whether it came from OSC 8, so the host can check the scheme first. |
PasteRequested |
Raised before anything is pasted, from PasteAsync, the paste keys and right-click alike. The handler sees the clipboard's text in PasteRequestedEventArgs and can replace it, set Cancel, or hold the paste with GetDeferral() while it asks the user. The terminal does its own bracketing and paste announcement afterwards, so Text is the bare text. |
HoveredLinkChanged |
Raised when HoveredLink changes: the pointer moved onto a link, from one link to another, or off one. Once per change, never for moves within a link. |
Keyboard shortcuts
The view handles the standard terminal keyboard operations itself. The chords follow the platform's own terminals: the clipboard lives on Ctrl+Shift on Windows and Linux because plain Ctrl+C is SIGINT and plain Ctrl+V is readline's quoted-insert, and on Cmd on macOS, which no shell binds.
| Action | Windows / Linux | macOS |
|---|---|---|
| Copy | Ctrl+Shift+C, Ctrl+Insert (Ctrl+C too, when there is a selection) | Cmd+C, Ctrl+Shift+C |
| Paste | Ctrl+Shift+V, Shift+Insert | Cmd+V, Ctrl+Shift+V |
| Select the input | Ctrl+Shift+A | Cmd+A, Ctrl+Shift+A |
| Zoom in / out / reset | Ctrl+Plus / Ctrl+Minus / Ctrl+0 | Cmd+Plus / Cmd+Minus / Cmd+0 |
| Scroll a page | Shift+PgUp / Shift+PgDn | Cmd+PgUp / Cmd+PgDn |
| Scroll to top / bottom | Ctrl+Shift+Home / Ctrl+Shift+End | Cmd+Home / Cmd+End |
Shift+Home and Shift+End are not scroll keys here: with Shift+arrows they extend a keyboard selection from the cursor, as in a text field. Scrolling the scrollback is left to a full-screen application (vim, less) while it has the alternate screen, since there is nothing to scroll.
ShortcutMode.Desktop adds the desktop map on Windows and Linux — Ctrl+A selects the input, Ctrl+V
pastes and Ctrl+X cuts, with Ctrl+Shift carrying the control character each would otherwise have sent.
ShortcutMode.None hands the whole keyboard to the program and turns every shortcut above off.
The same table is published as Avalonia KeyGestures on TerminalKeyGestures, so a host can show the
chords in its menus and drive the same operations through CopyAsync, PasteAsync, SelectInputAsync,
ZoomIn, ScrollPageUp and friends:
var zoomIn = new MenuItem { Header = "Zoom _In", InputGesture = TerminalKeyGestures.ZoomIn[0] };
zoomIn.Click += (_, _) => Terminal.ZoomIn();
Render frame rate
Terminals repaint on a shared, throttled frame rather than on every chunk of output, so a window hosting several of them does one invalidation pass instead of one per terminal per chunk. The rate defaults to 30 FPS and is settable:
using Iciclecreek.Terminal;
TerminalRenderThrottle.TargetFrameRate = 60; // valid range 1–1000
Raise it for a smoother repaint on a high-refresh display, or lower it to hand UI-thread time back to the rest of the app — a terminal streaming build output at 10 FPS is still perfectly readable and costs a third of the invalidations. Because the frame is shared, the setting is global rather than per-terminal: it applies to every terminal already open, from the next frame scheduled. Safe to set from any thread.
Graphics
Two image protocols are decoded by XTerm.NET and drawn by the terminal — Sixel (ESC P … q … ESC \)
and Kitty (ESC _ G … ESC \). img2sixel, chafa, lsix, timg, icat, yazi and image.nvim
work with no configuration. An image behaves like terminal content rather than an overlay: typing
over it replaces that part of the picture, clear removes it, and it scrolls with the text around it
and is freed when it falls out of the scrollback.
Animated Kitty images play on their own. The terminal runs a clock only while something is actually animating, advances by elapsed time rather than one frame per tick — so a late repaint stutters an animation rather than slowing it down — and re-uploads a picture's texture only when its frame actually changes.
Two things are handled for you and are worth knowing about:
- The cell size measured from your font is published to the emulator and is the answer given to a
CSI 16 tquery. That is what applications use to size their images, so a picture lines up with the grid it was drawn for — including after a font change or a move to a display with different scaling. - A picture is uploaded once and re-blitted on every frame after that, not re-decoded; the upload is
released when the terminal drops the picture. Wherever Avalonia runs on Skia, the pictures in front
of the text are drawn by a small picture layer from GPU textures made once per picture, so a screen
full of pictures costs draws, not bandwidth. Text is always drawn through
DrawingContext.
Sixel is drawn as one image per line, however many Sixels landed on it. XTerm.NET keeps the pixels each line shows rather than every picture that painted them, so a program that repaints small regions over and over — a cursor, a hover, a diffing framebuffer such as SixelBuffer — costs at most one draw per row. The strip is drawn over the text and under any Kitty picture in front of it, and is uploaded again only when its pixels change.
A Kitty picture is held as a run per line. Each run carries the source rectangle and the columns it covers; the picture layer gathers the rows of one placement and draws the picture once, clipped to them. On a backend with no raster surface — Consolonia, for instance — images are skipped and the text still renders.
Pictures may overlap, and a row is drawn one run at a time from the back forwards, with the text going down between the ones behind it and the ones in front. That ordering is the whole of the compositing: a translucent picture blends over whatever was drawn under it because it is drawn after it. A cell's own background is painted by the bottom-most picture covering it and by no other, since painting it again nearer the front would erase what is behind rather than let it show through.
A run keeps its natural width even when the window is too narrow to show it, so the renderer draws as much as fits and narrows the source by the same proportion. Narrowing the window shows less of a picture and widening it shows more; nothing is destroyed in between.
Either protocol can be turned off. Switching Sixel off also stops the terminal advertising it, so applications send text instead of pictures rather than pictures that get dropped:
terminalControl.Terminal.Options.SixelEnabled = false;
terminalControl.Terminal.Options.KittyGraphicsEnabled = false;
Kitty's file, temp-file and shared-memory transmission media (t=f, t=t, t=s) are deliberately
refused — they would have the terminal open a path chosen by the process it is hosting. Clients are
told so and fall back to sending the pixels directly.

Links
- GitHub Repository: https://github.com/tomlm/Iciclecreek.Avalonia.TerminalWindow
- NuGet Package: https://www.nuget.org/packages/Iciclecreek.Avalonia.Terminal
- XTerm.NET: https://github.com/tomlm/XTerm.NET
- Porta.Pty: https://github.com/tomlm/Porta.Pty
- Avalonia UI: https://avaloniaui.net/
Authors
- Tom Laird-McConnell — tomlm
- John Campion Jr — JohnCampionJr
License
This project is licensed under the MIT License - see the LICENSE file for details.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Avalonia (>= 12.0.4)
- Avalonia.Skia (>= 12.0.4)
- Porta.Pty (>= 2.2.4)
- SkiaSharp.HarfBuzz (>= 3.119.4)
- Unicode.net (>= 2.0.0)
- Wcwidth (>= 4.0.1)
- XTerm.NET (>= 3.0.3)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Iciclecreek.Avalonia.Terminal:
| Package | Downloads |
|---|---|
|
Bashka.Plugins.Core
Package Description |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 4.1.4 | 828 | 11/9/2026 |
| 4.1.3 | 620 | 11/2/2026 |
| 4.1.2 | 251 | 10/29/2026 |
| 4.1.1 | 498 | 10/24/2026 |
| 4.1.0 | 2,322 | 10/14/2026 |
| 4.1.0-rc001 | 101 | 10/14/2026 |
| 4.0.8 | 194 | 10/13/2026 |
| 4.0.7 | 178 | 10/11/2026 |
| 4.0.6 | 314 | 10/8/2026 |
| 4.0.5 | 171 | 10/6/2026 |
| 4.0.4 | 310 | 10/6/2026 |
| 4.0.3 | 820 | 10/1/2026 |
| 4.0.2 | 5,145 | 9/6/2026 |
| 4.0.1 | 183 | 9/2/2026 |
| 4.0.1-rc002 | 142 | 9/2/2026 |
| 4.0.1-rc001 | 80 | 9/1/2026 |
| 4.0.0 | 109 | 9/1/2026 |