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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Iciclecreek.Avalonia.Terminal" Version="4.1.4" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Iciclecreek.Avalonia.Terminal" Version="4.1.4" />
                    
Directory.Packages.props
<PackageReference Include="Iciclecreek.Avalonia.Terminal" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Iciclecreek.Avalonia.Terminal --version 4.1.4
                    
#r "nuget: Iciclecreek.Avalonia.Terminal, 4.1.4"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Iciclecreek.Avalonia.Terminal@4.1.4
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Iciclecreek.Avalonia.Terminal&version=4.1.4
                    
Install as a Cake Addin
#tool nuget:?package=Iciclecreek.Avalonia.Terminal&version=4.1.4
                    
Install as a Cake Tool

Icon

Iciclecreek.Avalonia.Terminal For Avalonia 12.x

Terminal Demo

A cross-platform XTerm terminal emulator control for Avalonia UI applications.

Build Status NuGet License

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

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 t query. 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.

Kitty

Authors

License

This project is licensed under the MIT License - see the LICENSE file for details.

Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
Loading failed